An MCP Server for Real-Time Trends: Setup Guide

An MCP server for real-time trends lets AI agents and assistants pull live social and search velocity data through a standard interface. Model Context Protocol (MCP) is an open-source standard that connects AI applications such as Claude and ChatGPT to external data sources, tools and workflows, often described as a USB-C port for AI. The latest documented specification version is 2026-07-28, according to modelcontextprotocol.io. TrendsAGI ships an official Python client that includes an MCP server (trendsagi mcp) for Claude Desktop, Claude Code, Cursor, VS Code and any other MCP client, as listed on pypi.org for version 0.14.0.

This guide shows how to install the local stdio server or use the hosted endpoint, which tools an agent can call, and how to chain them into a practical workflow that finds a rising topic, inspects its analytics and AI insights, and surfaces a recommendation for human review. All measurements remain snapshot-based: velocity is posts per hour from stored data, not a forecast or unique-user count.

What MCP provides for trend intelligence

MCP servers expose three core primitives: tools (model-controlled), resources (application-controlled) and prompts (user-controlled). TrendsAGI’s MCP server focuses on tools that return measured trend data, AI-generated insights and intelligence recommendations. The same tools are available through the Python SDK’s TrendsAGITools class, so an agent can run locally or inside any MCP-compatible client without rewriting the logic.

TrendsAGI detects topics gaining attention, measures velocity and growth, explains them with summaries, key themes, sentiment, audience and marketing angles, and turns the evidence into recommendations, crisis alerts and watchlist alerts. The platform is built for marketers, growth and paid-media teams, creators, newsrooms, PR and operations teams, and developers building AI agents.

Install the local MCP server

Install the package with MCP support:

pip install "trendsagi[mcp]"

Requires Python 3.10+. Set the API key as an environment variable (keys are created in the account profile):

export TRENDSAGI_API_KEY=your_key_here

Launch the server:

trendsagi mcp

or the equivalent command trendsagi-mcp. By default every tool is read-only. To expose write tools such as add_to_watchlist and update_recommendation, start with the flag:

trendsagi mcp --allow-writes

For Claude Code the one-line addition is:

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

For Claude Desktop, Cursor or VS Code place this JSON in the client’s MCP configuration:

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

The local server uses stdio and authenticates with the API key supplied in the environment. A hosted MCP endpoint is also available at https://api.trendsagi.com/mcp and supports OAuth sign-in for remote clients, according to the package documentation on pypi.org.

Hosted endpoint versus local stdio server

The local stdio server runs on the same machine as the client, keeps the API key inside the process environment, and is ideal for development or air-gapped environments. The hosted endpoint removes the need to run a local process and authenticates via OAuth, which is convenient for shared or cloud-based agents. Both surfaces expose the same tool set; the choice is mainly about where the process lives and how credentials are managed.

Available tools

The MCP server and the TrendsAGITools class expose the following tools (read-only by default):

• list_trends
• list_trend_categories
• search_trend_insights
• get_trend
• get_trend_ai_insights
• get_trend_analytics
• list_recommendations
• list_crisis_events
• list_watchlist
• get_api_usage
• find_capability (version 0.14.0+)

When allow_writes is enabled the write tools add_to_watchlist and update_recommendation become available. Tool calls return a dictionary: success yields {"result": <data>}; failure yields {"error": "...", "detail": "..."}. Agents should always inspect the returned structure rather than assuming success.

Python SDK and agent tools

Install the core package:

pip install trendsagi

Create a client and the tools wrapper:

import os
from trendsagi import TrendsAGIClient, TrendsAGITools

client = TrendsAGIClient(api_key=os.environ["TRENDSAGI_API_KEY"])
tools = TrendsAGITools(client)  # read-only
# tools = TrendsAGITools(client, allow_writes=True)  # opt-in writes

Obtain framework-specific tool definitions:

openai_tools = tools.openai()          # Chat Completions format
responses_tools = tools.openai_responses()  # Responses API
anthropic_tools = tools.anthropic()    # Claude tool use
langchain_tools = tools.langchain()    # LangChain

Execute a tool by name:

result = tools.call("list_trends", {"category": "Technology", "sort_by": "velocity", "limit": 5})
trends = result["result"]["trends"]
trend_id = trends[0]["id"]

Other common calls:

insights = tools.call("get_trend_ai_insights", {"trend_id": trend_id})
analytics = tools.call("get_trend_analytics", {"trend_id": trend_id, "period": "7d"})
recs = tools.call("list_recommendations", {"limit": 10, "priority": "high"})
usage = tools.call("get_api_usage", {})

The underlying REST client methods remain available for non-agent code:

client.get_trends(category="Technology", sort_by="velocity", limit=5)
client.get_ai_insights(trend_id)
client.get_trend_analytics(trend_id, period="7d")
client.search_insights(key_theme_contains="AI chips")
client.get_recommendations(limit=10, priority="high")
client.create_topic_interest(keyword="...", alert_condition_type="volume_threshold", volume_threshold_value=500)

Safety defaults and rate limits

Tools are read-only unless the server or Tools instance is started with allow_writes. Write operations such as adding a watchlist entry or updating a recommendation therefore require an explicit opt-in. Ad-platform connectors (Google Ads, Meta Ads and Conversions API, TikTok Ads, LinkedIn Ads, Microsoft Ads, Pinterest Ads, Snapchat Ads, Reddit Ads) preview every change before any explicit execution; agents never push live budget or creative modifications without that human-visible preview step.

Call get_api_usage regularly to observe remaining quota. The method returns the account’s current consumption so an agent can throttle itself or surface a message when limits are approached. Exact plan quotas are shown on the subscription page; the free Developer tier exists, but higher-tier numbers are not restated here.

End-to-end example: rising Technology trend to campaign proposal

The following sequence is suitable for an agent that must stay inside the read-only boundary and produce a recommendation for human approval.

import os
from trendsagi import TrendsAGIClient, TrendsAGITools

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

# 1. Surface the fastest-moving Technology trends
list_result = tools.call("list_trends", {
    "category": "Technology",
    "sort_by": "velocity",
    "limit": 5
})
trends = list_result["result"]["trends"]
if not trends:
    print("No trends returned")
else:
    top = trends[0]
    trend_id = top["id"]
    name = top["name"]

    # 2. Inspect recent analytics
    analytics = tools.call("get_trend_analytics", {
        "trend_id": trend_id,
        "period": "7d"
    })

    # 3. Pull AI insights (summary, themes, sentiment, audience, marketing angles)
    insights = tools.call("get_trend_ai_insights", {"trend_id": trend_id})

    # 4. Look for existing high-priority recommendations
    recs = tools.call("list_recommendations", {
        "limit": 5,
        "priority": "high"
    })

    # 5. Check remaining quota
    usage = tools.call("get_api_usage", {})

    # Agent now composes a human-readable proposal that cites the measured
    # velocity, the insight themes and any matching recommendation.
    # No write tool is called; the proposal is returned for approval.

Because the Tools instance was created without allow_writes, the agent cannot accidentally mutate watchlists or recommendations. The proposal can later be turned into an explicit update_recommendation call once a human has reviewed the evidence.

Webhooks and additional delivery options

For continuous monitoring outside an interactive agent session, TrendsAGI supports signed outbound webhooks. Create a subscription with POST /api/integrations/webhooks supplying url, trigger_type (trend_velocity or trend_category), delivery_mode, threshold_value, keywords and cooldown_seconds. New subscriptions start paused; send a test delivery, then activate with a PATCH. Each delivery carries the header X-Webhook-Signature containing the lowercase hex HMAC-SHA256 of the exact raw body. Verify the signature with a constant-time comparison against the unmodified bytes. The precise field list of the body is obtained by inspecting a test delivery; do not invent field names.

Slack notifications, Google Sheets exports and the listed ad-platform connectors are also available. Zapier, Make and n8n connect through the same webhooks and REST API; there is no native app for those platforms.

Frequently asked questions

What is an MCP server and how does it deliver real-time trend data to AI agents?

An MCP server is a process that implements the Model Context Protocol, exposing tools, resources and prompts that AI applications can call through a uniform interface. TrendsAGI’s MCP server returns measured trend velocity, growth, AI insights and recommendations so agents receive evidence-backed context without custom API glue.

How do I install and configure the TrendsAGI MCP server in Claude, Cursor or VS Code?

Install with pip install "trendsagi[mcp]", set TRENDSAGI_API_KEY, then either run trendsagi mcp or add the JSON configuration block shown above that points the client at the trendsagi-mcp command. Claude Code can be configured with a single claude mcp add command.

Which tools does the TrendsAGI MCP server expose and what can an agent query?

The read-only set includes list_trends, get_trend, get_trend_ai_insights, get_trend_analytics, list_recommendations, list_crisis_events, list_watchlist, search_trend_insights, get_api_usage and find_capability. Write tools appear only when allow_writes is enabled.

What are the differences between the hosted MCP endpoint and the local stdio server?

The local server runs via stdio with an environment-supplied API key; the hosted endpoint at https://api.trendsagi.com/mcp supports OAuth for remote clients. Tool behaviour is identical; the difference is process location and authentication method.

What plan limits and API quotas apply when using the MCP server?

Quotas are account-specific and can be inspected at any time with the get_api_usage tool. Exact numbers for paid plans are listed on the subscription page; the free Developer tier is available.

How does TrendsAGI's trend intelligence differ from generic real-time data MCP servers?

TrendsAGI measures velocity as posts per hour from stored snapshots, supplies AI insights that include summary, key themes, sentiment, audience and marketing angles, and produces evidence-backed recommendations and crisis alerts. Generic servers typically expose raw feeds without the same normalised velocity metrics or recommendation layer.

How we researched this

Prepared by TrendsAGI Research. Facts checked on 17 October 2026 against the sources listed below.

Capability descriptions and code use TrendsAGI's documented REST API, Python SDK and MCP server. External facts come from the sources below.

We re-research and rewrite this page at least every four months; the updated date only changes when the facts are re-checked.

Sources

• What is the Model Context Protocol (MCP)? — modelcontextprotocol.io
• trendsagi 0.14.0 (PyPI / TrendsAGI) — pypi.org
• Trends MCP | MCP Server & API for AI Assistants & Agents — trendsmcp.ai

Try it with TrendsAGI

• Install the Python SDK with agent tools and the MCP server
• TrendsAGI API documentation
• More guides and trend analysis