MCP & API Reference
Query behavioral trend data across search, social, and commerce platforms. Use MCP to query via an AI assistant like Claude or ChatGPT, or the REST API to integrate directly into your code.
Free API access
Get your free API key
100 free requests per month. No credit card, no setup fee.
Replaced my manual Google Trends scraper in an afternoon. The data is clean and the latency is surprisingly low for a free tier.
We use it for keyword trend reports. The free daily limit keeps us batching queries for weekly digests. Upgrading is there when we need more headroom.
Hooked it into my MCP server in like 20 minutes. The JSON response is well-structured and the docs are solid. Exactly what I needed.
We pipe weekly series into BigQuery for a few brand cohorts. Compared to maintaining our old Selenium job, this is boring in the best way. Uptime has been solid.
Great for slide-ready trend screenshots when leadership asks why we are prioritizing a feature. I wish the dashboard had saved views, but the API side is great.
Running it from Cursor with the MCP config took one try. I am not a trends person, but my side project now emails me when a niche keyword spikes hard week over week.
Using the growth endpoints to sanity-check retail names before I write up notes. Occasionally the normalization differs from what I see in the raw Google UI, but it is consistent run to run.
Pulling multi-source ranked lists into a notebook is straightforward. Error payloads are actually readable when I fat-finger a parameter, which matters more than people admit.
Does what it says. I knocked a star because onboarding assumed I already knew MCP wiring; a copy-paste block for Claude Desktop would have saved me 15 minutes.
We track TikTok hashtag momentum against paid spend in a Looker sheet. Not glamorous work, but it is the first tool my team did not argue about during rollout.
Retries are predictable and I have not seen weird HTML in responses (looking at you, scrapers). Would pay for a team key rotation flow, but for now we rotate manually.
Quick checks on retail buzz before we dig into filings. Not a silver bullet, but it is faster than opening twelve browser tabs and reconciling by hand.
Helpful for spotting whether a topic is a one-day meme or sticking around. I still cross-check with Search Console, but this gets me 80% of the signal in one call.
I demo this in workshops when people ask how to ground LLM answers in something fresher than training data. The MCP angle lands well with engineers who hate glue code.
Solid for client reporting. Billing is clear enough that finance stopped asking me what line item this is. Minor nit: peak hours can feel a touch slower, still acceptable.
I wired this behind a small CLI for contributors who want trend context in issues. Keeping the surface area tiny matters for OSS, and the schema has not churned on me yet.
Daily pulls for a 30-day window go straight into our internal scoreboard. Stakeholders finally stopped debating whose screenshot of Trends was newer.
We are pre-revenue, so free tier discipline matters. I hit the cap once during a brainstorm where everyone wanted to try random keywords. Learned to batch smarter.
Security review passed without drama: HTTPS, scoped keys, no bizarre third-party redirects in the chain we could find. That is rarer than vendors think.
I do not need this daily, but when App Store rank shifts look weird, having Reddit and news context in one place saves me from context switching across six apps.
I use it to see if a story is genuinely blowing up or just loud on one platform. It is not a replacement for reporting, but it keeps my ledes honest.
We moved off a brittle Playwright script that broke every time Google shuffled markup. Same data shape every week now, which is all I wanted from life.
Seasonal demand spikes line up with what we see in Amazon search interest here. Merch team stopped sending me screenshots from random tools that never matched.
Solid for client decks. I docked one star only because I still export to Sheets manually; a direct connector would be nice someday.
Steam concurrents plus Reddit chatter in one workflow beats our old spreadsheet ritual before milestone reviews.
Quick pulse on whether a feature name is confusing people in search before we ship copy. Cheap sanity check compared to a full survey.
Monitored from Grafana via a thin wrapper. p95 stayed under our SLO budget last month. One noisy day during a holiday but nothing alarming.
Narrative fights in meetings got shorter once we could point at the same trend line everyone agreed on. Sounds silly until you have lived through it.
Using normalized series as a weak prior in a forecasting experiment. Citation-friendly timestamps in the payload made reproducing runs less painful.
Approved for our pilot group after a quick vendor review. Would love SAML, not a blocker for our size.
YouTube search interest plus TikTok hashtags in one place helps me explain why a sponsor should care about a vertical without hand-waving.
Cron job hits the API before standup; Slack gets a compact summary. Took an afternoon to wire, has been stable for two quarters.
Useful for public-interest topics where search interest is a rough proxy for attention. I still triangulate with primary sources; this is one signal among several.
Runs in a VPC egress-only subnet with allowlisted domains. Fewer exceptions to explain to auditors than our last vendor.
Spotting when a topic is about to flood Discord saves my team from reactive moderation fires. Not perfect, but directionally right often enough.
For lean teams the ROI story writes itself. I would not build an in-house scraper for this anymore unless compliance forced it.
Examples in the docs match what the MCP actually returns. You would be surprised how rare that is in this category.
Pager stayed quiet. When something upstream flaked once, the error string told me which parameter to fix without opening logs first.
Students use it for coursework demos. Budget is tight so free tier matters; we coach them to cache aggressively.
Helps prep talking points when retail interest in our name swings after earnings. Not material disclosure, just context for Q&A prep.
Response sizes stay small enough for mobile hotspots. I hate APIs that dump megabytes for a sparkline.
What are you working on?
How will you connect?
Connect
Add to your AI in 30 seconds
An API key is required to connect. Get your free key above, then copy the pre-filled config for your client.
Cursor
Cursor Settings → Tools & MCP → Add a Custom MCP Server
"trends-mcp": { "url": "https://api.trendsmcp.ai/mcp", "transport": "http", "headers": { "Authorization": "Bearer YOUR_API_KEY" } }
+ Add to Cursor
Or paste into Mac / Linux — ~/.cursor/mcp.json
Windows — %USERPROFILE%\.cursor\mcp.json
↑ Get your free key above first — the config won't work without it.
Claude Desktop
User → Settings → Developer → Edit Config — add inside mcpServers
"trends-mcp": { "command": "npx", "args": [ "-y", "mcp-remote", "https://api.trendsmcp.ai/mcp", "--header", "Authorization:${AUTH_HEADER}" ], "env": { "AUTH_HEADER": "Bearer YOUR_API_KEY" } }
Mac — ~/Library/Application Support/Claude/claude_desktop_config.json
Windows — %APPDATA%\Claude\claude_desktop_config.json
Fully quit and restart Claude Desktop after saving.
Claude Code (CLI)
claude mcp add --transport http trends-mcp https://api.trendsmcp.ai/mcp \ --header "Authorization: Bearer YOUR_API_KEY"
Windsurf
Settings → Advanced Settings → Cascade → Add custom server +
"trends-mcp": { "url": "https://api.trendsmcp.ai/mcp", "transport": "http", "headers": { "Authorization": "Bearer YOUR_API_KEY" } }
Mac / Linux — ~/.codeium/windsurf/mcp_config.json
Windows — %USERPROFILE%\.codeium\windsurf\mcp_config.json
Or: Command Palette → Windsurf: Configure MCP Servers
VS Code
Extensions sidebar → search @mcp trends-mcp → Install — or paste manually into .vscode/mcp.json inside servers
"trends-mcp": { "type": "http", "url": "https://api.trendsmcp.ai/mcp", "headers": { "Authorization": "Bearer YOUR_API_KEY" } }
Paste into .vscode/mcp.json, or:
Command Palette (⇧⌘P / Ctrl+Shift+P) → MCP: Add Server
Authentication
Every request must include your API key as a Bearer token in the Authorization header.
Get a free key at trendsmcp.ai. 100 requests/month, no credit card.
How calls are counted is defined below (same rules for REST and MCP).
curl -X POST https://api.trendsmcp.ai/api \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"source":"google search","keyword":"bitcoin"}'
import requests
res = requests.post(
"https://api.trendsmcp.ai/api",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={"source": "google search", "keyword": "bitcoin"}
)
res.raise_for_status()
data = res.json()
const res = await fetch("https://api.trendsmcp.ai/api", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify({ source: "google search", keyword: "bitcoin" })
});
const data = await res.json();
What counts as a request
Each successful hit against the data API uses one unit of your monthly quota.
One source + keyword per HTTP request or MCP tool call counts as one request.
One source + keyword per call counts as one request, including every entry in percent_growth in that same call.
Counted per feed (type) and per page. Example with limit 25: offset 0 is one request, offset 25 is another for the same type. Different feeds are separate. If one response includes several feeds, each feed is counted per page on its own.
Data Sources
Two types of sources are available, accessed via different operations. Keyword sources return a historical time series or growth metric for a specific keyword. Live feeds return the top-ranked items on a platform right now — no keyword needed.
Keyword sources — Get Trends & Get Growth
Pass the source value below in your request body alongside keyword.
Scores are normalized to a 0–100 scale where the pipeline supports it.
| source | Description | Keyword format |
|---|---|---|
google search | Google search volume | Any keyword or phrase |
google images | Google image search volume | Any keyword or phrase |
google news | Google News search volume | Any keyword or phrase |
google shopping | Google Shopping search volume | Any keyword or phrase |
youtube | YouTube search volume | Any keyword or phrase |
tiktok | TikTok hashtag volume | Hashtag or topic |
reddit | Subreddit subscriber metrics (not post or mention volume). Get Trends: time series of subscriber levels. Get Growth: subscriber growth across the periods you request. | Subreddit name only, no r/ prefix (e.g. wallstreetbets). Typical window is about the last 30 days. |
amazon | Amazon product search volume | Product name or category |
wikipedia | Wikipedia page views | Article title or topic |
news volume | News article mention volume | Any keyword or phrase |
news sentiment | News sentiment score (positive / negative) | Any keyword or phrase |
webtraffic | Website traffic / domain popularity estimates | Domain or site identifier as supported by the pipeline |
app downloads | Mobile app download / install estimates (Android track) | Package id or app identifier; some responses include rank or price fields when available |
npm | npm package weekly downloads | Exact package name e.g. react |
steam | Steam concurrent players (monthly) | Game display name e.g. Elden Ring |
Live feeds — Get Top Trends
Pass the type value below with mode: "top_trends". No keyword needed.
Returns the current ranked leaders on that platform (e.g. the top 25 trending hashtags on TikTok right now).
| type | Platform / feed |
|---|---|
Google Trends | Top trending search terms on Google right now |
Google News Top News | Top news stories from Google News |
TikTok Trending Hashtags | Top trending hashtags on TikTok |
YouTube Trending | Top trending videos on YouTube |
X (Twitter) Trending | Top trending topics on X |
Reddit Hot Posts | Hottest posts on Reddit's front page |
Reddit World News | Top posts in r/worldnews |
Wikipedia Trending | Most-viewed Wikipedia articles today |
Amazon Best Sellers Top Rated | Amazon top-rated best sellers across all categories |
Amazon Best Sellers by Category | Amazon best sellers filtered by product category |
App Store Top Free | Top free apps on the iOS App Store |
App Store Top Paid | Top paid apps on the iOS App Store |
Google Play | Top apps on Google Play |
Top Websites | Most-visited websites globally by traffic rank |
Spotify Top Podcasts | Top podcasts on Spotify |
MCP / AI
AI Prompts
When using Trends MCP through an AI assistant (Claude, ChatGPT, Cursor, etc.), include "using TrendsMCP" or "via TrendsMCP" in your prompt so the AI routes to the MCP instead of a web search.
nvidia over the past 5 years."ozempic over the last month."Stanley cup."Bitcoin weekly."air fryer over 5 years."langchain weekly."Elden Ring."Tesla over the last year."wallstreetbets on Reddit."GLP-1 grown over the past 12 months?"Anthropic on Google Search."Duolingo?"weight loss drugs across Google, TikTok, and Amazon."Meta changed over the past 6 months?"AI agents from Jan 2025 to Jan 2026."wallstreetbets on Reddit over the last 30 days?"running shoes."Electronics."
Live leaderboards: MCP tools require one feed (type) per call. The REST Get Top Trends request can omit type to return every feed in one response.
Routing
All requests go to a single POST / endpoint.
The operation is selected by the fields you include in the request body.
| Operation | Required fields |
|---|---|
| Get Trends | source + keyword (no percent_growth) |
| Get Growth | source + keyword + percent_growth |
| Get Top Trends | mode: "top_trends" |
/
Get Trends
Returns a full historical time series for a keyword from a single source.
For Google Search (and other Google verticals where the backend supports it), the default is long-range weekly data; data_mode: "daily" requests a recent daily window (typically about the last 30 days).
Many other sources use a fixed cadence or ignore data_mode. Always interpret the returned dates as source-native.
Quota: 1 request per source + keyword. Full rules
Request body
| Field | Type | Required | Description |
|---|---|---|---|
source |
string | Required | Data source. See Data Sources. |
keyword |
string | Required | Keyword, brand, product, or topic. |
data_mode |
string | Optional | REST only: "weekly" or "daily" where the source supports Google-style modes; otherwise ignored or N/A. MCP tool schemas do not expose this field; omit it when using MCP. |
Response fields
| Field | Type | Description |
|---|---|---|
date | string | ISO 8601 date e.g. "2026-03-21" |
value | number | Normalized trend score, 0–100. |
volume | number | null | Absolute volume where available. null otherwise. |
keyword | string | The keyword queried. |
source | string | The data source used. |
{
"source": "google search",
"keyword": "bitcoin",
"data_mode": "weekly"
}
[
{
"date": "2026-03-21",
"value": 47,
"volume": 25853617,
"keyword": "bitcoin",
"source": "google search"
},
// ... up to 261 weekly data points
]
/
Get Growth
Calculates point-to-point percentage growth for a keyword over one or more time windows.
Supports preset strings ("12M", "YTD", etc.) or exact custom date pairs.
Quota: 1 request per source + keyword (all percent_growth periods in that call). Full rules
Request body
| Field | Type | Required | Description |
|---|---|---|---|
source |
string | Required | Data source. See Data Sources. |
keyword |
string | Required | Keyword, brand, or topic. |
percent_growth |
array | Required | Array of preset strings or custom date objects. See below. |
data_mode |
string | Optional | Same semantics as Get Trends: applies where supported (often Google sources); ignored or N/A for many pipelines. Not exposed on MCP tools. |
Growth period presets
7D14D30D1M2M3M
6M9M12M1Y18M24M
2Y36M3Y48M60M5Y
MTDQTDYTD
Custom date range object
| Field | Type | Description |
|---|---|---|
name | string | Optional label returned in results. |
recent | string | More recent date, YYYY-MM-DD. |
baseline | string | Baseline/comparison date, YYYY-MM-DD. |
Response fields
| Field | Type | Description |
|---|---|---|
search_term | string | The keyword queried. |
data_source | string | The source used. |
results | array | One object per period requested. |
period | string | Period identifier, e.g. "12M" or custom name. |
growth | number | Percentage change, positive or negative. |
direction | string | "increase" or "decrease". |
recent_date | string | ISO 8601 date of the recent data point. |
baseline_date | string | ISO 8601 date of the baseline point. |
recent_value | number | Normalized score at the recent date. |
baseline_value | number | Normalized score at the baseline date. |
volume_available | boolean | Whether absolute volume exists for this source. |
recent_volume | number | null | Absolute volume at the recent date. |
baseline_volume | number | null | Absolute volume at the baseline date. |
volume_growth | number | null | Volume growth %, if available. |
metadata | object | total_data_points, calculations_completed, all_successful. |
{
"source": "google search",
"keyword": "nike",
"percent_growth": ["12M", "3M", "YTD"]
}
{
"source": "amazon",
"keyword": "nike",
"percent_growth": [
{
"name": "Last Year",
"recent": "2025-12-31",
"baseline": "2024-12-31"
}
]
}
{
"search_term": "nike",
"data_source": "google search",
"results": [
{
"period": "12M",
"growth": -12.31,
"direction": "decrease",
"recent_date": "2026-03-21",
"baseline_date": "2025-03-22",
"recent_value": 57,
"baseline_value": 65,
"volume_available": true,
"recent_volume": 24158298,
"baseline_volume": 27548936,
"volume_growth": -12.31
}
],
"metadata": {
"total_data_points": 261,
"calculations_completed": 1,
"all_successful": true
}
}
/
Get Top Trends
Returns ranked items from live platform feeds stored for Trends MCP.
On the REST API, omit type to aggregate every feed in one response (same semantics the handler uses internally).
On MCP, the get_top_trends tool requires an explicit type per call. There is no single MCP invocation that returns all feeds at once.
Quota: per feed (type) and per page (limit / offset). Full rules
Request body
| Field | Type | Default | Description |
|---|---|---|---|
mode | string | Set to "top_trends". | |
type | string | all (REST) | REST: optional; omit for all feeds. MCP: required (one feed per tool call). |
limit | integer | 25 | Max items per feed (up to 200). |
offset | integer | 0 | REST: skip this many rows per feed for pagination (when the backend supports it for that feed). |
Available feeds
Amazon Best Sellers by Category
Amazon Best Sellers Top Rated
App Store Top Free
App Store Top Paid
Google News Top News
Google Play
Google Trends
Reddit Hot Posts
Reddit World News
Top Websites
Spotify Top Podcasts
TikTok Trending Hashtags
Wikipedia Trending
X (Twitter) Trending
YouTube Trending
{
"mode": "top_trends",
"type": "Google Trends",
"limit": 10
}
{
"as_of_ts": "2026-03-26T22:22:25Z",
"type": "Google Trends",
"limit": 10,
"count": 10,
"data": [
[1, "chuck norris"],
[2, "project hail mary"],
[3, "bachelorette cancelled"]
// ... [rank, name] pairs
]
}
Errors
Errors return JSON with an error string and message. HTTP status may be 4xx/5xx depending on the failure; some upstream gaps are reported as data_unavailable (or similar) with a generic message rather than not_found.
| Status | Error code | Meaning |
|---|---|---|
| 400 | missing_parameter | Required field missing from request body |
| 400 | invalid_source | Unrecognized source value (message may list allowed values) |
| 401 | Missing or invalid API key | |
| 404 | not_found | No series or entity matched this keyword/source (when the pipeline classifies it that way) |
| varies | data_unavailable | Pipeline could not return data (temporary gap, unsupported query, or empty upstream). HTTP status is not always 404; read message. |
| 429 | rate_limited | Monthly request limit reached. Upgrade for more. |
| 500 | internal_error | Unexpected server error |
Additional codes can appear as the data layer evolves; treat message as the operator-facing detail.
{
"error": "missing_parameter",
"message": "The 'keyword' parameter is required."
}