TrendsAGI

TrendsAGI

Real-time trend intelligence for your code and your AI agents: what is trending on social platforms right now, with measured volume, velocity and growth, AI insights on why each topic is moving, evidence-backed recommendations, crisis alerts and watchlists. Paid media and growth teams use it to target what is rising, time spend to the trend curve and brief creative on measured demand.

Install

pip install trendsagi            # client, agent tools and the trendsagi command

pip install "trendsagi[mcp]" # adds the local MCP server (Python 3.10+) pipx install trendsagi # just the command line, in its own environment npx trendsagi --help # or the same command line from npm (Node.js 18+)

Create an API key under Profile > API Keys at app.trendsagi.com and export it:

export TRENDSAGI_API_KEY="your_api_key"

Quickstart

import os

from trendsagi import TrendsAGIClient

client = TrendsAGIClient(api_key=os.environ["TRENDSAGI_API_KEY"])

Fastest-moving Technology topics right now

trends = client.get_trends(category="Technology", sort_by="velocity", limit=5) for trend in trends.trends: print(trend.id, trend.name, trend.volume)

Why is the top one moving?

insight = client.get_ai_insights(trends.trends[0].id) if insight: print(insight.sentiment_summary, insight.key_themes)

Command line

trendsagi login                  # paste an API key; saved to ~/.config/trendsagi/config.json

trendsagi trends list --category Technology --sort velocity --limit 10 trendsagi insights get 123 # audience, sentiment and marketing angles trendsagi sql "SELECT category, count(*) FROM trends GROUP BY 1 ORDER BY 2 DESC" trendsagi recommendations list --priority high trendsagi watchlist add "oat milk" --threshold 50000 --email trendsagi api /api/integrations/delivery/health -q lookback_hours=24 # any endpoint

Every command has --help. In a terminal, lists print as tables; piped or with --json they print JSON, so trendsagi trends list | jq works. The key comes from --api-key, then TRENDSAGI_API_KEY, then the saved login. Commands that delete something or change live ads ask first; pass --yes in scripts. Exit codes: 0 success, 1 API error, 2 invalid usage, 4 missing or rejected key.

The commands are declared once in src/trendsagi/cli_spec.json; a dependency-free Node.js build of the same CLI lives in npm/ and is published as trendsagi on npm. Guide: trendsagi.com/api-docs/integrations/cli.

The client calls any endpoint too: client.request("GET", "/api/integrations/delivery/health", params={"lookback_hours": 24}).

Use TrendsAGI in your AI assistant (no install)

Add the hosted MCP server, sign in to TrendsAGI and approve the connection:

https://api.trendsagi.com/mcp

Then ask *"What is accelerating fastest in Technology this week, and who should I target with it?"* The hosted tools are read-only, and each call counts as one API request. Each connection gets its own key, listed as "AI connector: " under Profile > API Keys; delete it to disconnect. Clients without OAuth can send an API key as Authorization: Bearer . Guide: trendsagi.com/mcp.

Build an agent with Cursor Agent SDK

Agent SDK defines agents as a folder of Markdown and TypeScript. Add TrendsAGI with one file and the agent gets the hosted MCP server's read-only tools by name:

// bot/mcp-connections/trendsagi.ts

import { defineConnection } from "@grok/agent-sdk/connections";

export default defineConnection({ url: "https://api.trendsagi.com/mcp", headers: { authorization: "Bearer ${TRENDSAGI_API_KEY}" }, // filled by Agent SDK, not JavaScript advertiseTools: true, effects: "read", });

agent-sdk run --dir . --message "What is rising fastest in Technology this week?"

agent-sdk/ is a complete project to copy: instructions, a trend-brief skill, hosting settings (egress to api.trendsagi.com, a TRENDSAGI_API_KEY secret) and smoke evals. Guide: trendsagi.com/api-docs/integrations/agent-sdk.

Use TrendsAGI from your browser's agent (WebMCP)

WebMCP lets a web page hand tools to the AI agent built into the browser (Chrome and Edge in origin trials, ChatGPT desktop, Brave Leo). While you are signed in to app.trendsagi.com, the app registers TrendsAGI's read-only tools with document.modelContext, so the agent uses them with your session: no connector or API key, and calls count as app use rather than API usage. trendsagi.com offers public tools (docs search, trend reports, plans and the free calculators) to every visitor.

To put TrendsAGI tools on your own site, register them in your page and run them on your server, which keeps the API key:

tools = TrendsAGITools(TrendsAGIClient(api_key=os.environ["TRENDSAGI_API_KEY"]))

tools.webmcp() # serve to your page: name, title, description, inputSchema, annotations tools.call("list_trends", args) # run the call your page forwards

webmcp/ has the browser module and a FastAPI server. Guide: trendsagi.com/webmcp.

Agent tools

One registry, every format. The tools are read-only by default; add_to_watchlist and update_recommendation appear only with allow_writes=True (or trendsagi mcp --allow-writes).

OpenAI

import json, os

from openai import OpenAI from trendsagi import TrendsAGIClient, TrendsAGITools

tools = TrendsAGITools(TrendsAGIClient(api_key=os.environ["TRENDSAGI_API_KEY"])) openai = OpenAI() messages = [{"role": "user", "content": "Find a fast-rising Technology trend and suggest a campaign angle."}]

while True: reply = openai.chat.completions.create(model="gpt-5-mini", messages=messages, tools=tools.openai()) message = reply.choices[0].message messages.append(message) if not message.tool_calls: print(message.content) break for call in message.tool_calls: result = tools.call(call.function.name, call.function.arguments) messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps(result)})

Claude, LangChain and others

tools.anthropic()         # Anthropic Messages API tools=

tools.openai_responses() # OpenAI Responses API tools= tools.langchain() # LangChain StructuredTools (pip install "trendsagi[langchain]") tools.webmcp() # WebMCP descriptors for document.modelContext.registerTool

With Claude, pass tools=tools.anthropic() and answer each tool_use block with {"type": "tool_result", "tool_use_id": block.id, "content": json.dumps(tools.call(block.name, block.input))}. tools.call never raises: errors come back as {"error": ...} so the model can read a rate limit or a bad argument and recover.

Local MCP server

pip install "trendsagi[mcp]"

claude mcp add trendsagi --env TRENDSAGI_API_KEY=your_api_key -- trendsagi mcp

Or in any MCP client's JSON config (Claude Desktop, Cursor, VS Code):

{ "mcpServers": { "trendsagi": { "command": "trendsagi-mcp", "env": { "TRENDSAGI_API_KEY": "your_api_key" } } } }

Query with SQL

For answers no single e