# TrendsMCP Docs

Last updated: 2026-07-26

> Markdown mirror of [Docs](https://www.trendsmcp.ai/docs). HTML UI: [docs](https://www.trendsmcp.ai/docs) · [Connect](https://www.trendsmcp.ai/docs#connect) · [llms.txt](https://www.trendsmcp.ai/llms.txt)

Two MCP hosts (not interchangeable):
- `https://api.trendsmcp.ai/mcp` — Bearer API key
- `https://www.trendsmcp.ai/mcp` — OAuth for Claude.ai Connectors only

REST: `POST https://api.trendsmcp.ai/api` with `Authorization: Bearer <key>`

## MCP tools

Three tools. Human titles and wire names:

| MCP tool name | Title | REST `mode` | What it returns |
| --- | --- | --- | --- |
| `get_trends` | Get Trends | `get_time_series` (alias: `get_trends`) | ~5 years weekly series for one source + keyword |
| `get_growth` | Get Growth | `get_growth` | % change over one or more periods |
| `get_top_trends` | Get Top Trends | `get_top_trends` | Live ranked feed (no keyword) |

Prefer REST `mode: "get_time_series"` in examples. MCP clients call `get_trends`. Tools are read-only.

## Get an API key

1. Open [Get API key](https://www.trendsmcp.ai/account?tab=signup) (or [Account](https://www.trendsmcp.ai/account)).
2. Enter your email and submit. No credit card required.
3. Your key is shown on the page and emailed to you (format `tmcp_liv…`).
4. Replace `YOUR_API_KEY` in the client configs below with that key.
5. Use it as `Authorization: Bearer <key>` for REST and for MCP on `api.trendsmcp.ai`.

Claude.ai Connectors use OAuth against `www.trendsmcp.ai/mcp` — no API key in that connector config.

## Setup

Primary UI (MCP + REST): [Docs → Connect](https://www.trendsmcp.ai/docs#connect)

### Claude (claude.ai — OAuth connector, recommended)
Uses the **www** OAuth endpoint, not api.
Claude.ai → Settings → Customize → Connectors → Add custom connector
- Name: Trends MCP
- Server URL: `https://www.trendsmcp.ai/mcp` (OAuth — intentional; different from api.)
Claude handles OAuth automatically — no API key in the connector config.
Deep link: `https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Trends%20MCP&connectorUrl=https%3A%2F%2Fwww.trendsmcp.ai%2Fmcp`
- [MCP setup for Claude](https://www.trendsmcp.ai/mcp-server-for-claude): Desktop, claude.ai connector, and Claude Code

### Claude Desktop
User → Settings → Developer → Edit Config — add inside `mcpServers` (Bearer on **api**)
```json
"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"
```

### Cursor
Cursor Settings → Tools & MCP → Add a Custom MCP Server (or use the Add to Cursor deep link on docs)
```json
"trends-mcp": {
  "url": "https://api.trendsmcp.ai/mcp",
  "transport": "http",
  "headers": { "Authorization": "Bearer YOUR_API_KEY" }
}
```
Mac/Linux: `~/.cursor/mcp.json` — Windows: `%USERPROFILE%\.cursor\mcp.json`
- [MCP setup for Cursor](https://www.trendsmcp.ai/mcp-server-for-cursor)

### Windsurf
Cascade MCP panel → Configure / Add custom server (or Command Palette → `Windsurf: Configure MCP Servers`).
Windsurf remote HTTP uses `serverUrl` (not Cursor’s `url` + `transport`).
```json
"trends-mcp": {
  "serverUrl": "https://api.trendsmcp.ai/mcp",
  "headers": { "Authorization": "Bearer YOUR_API_KEY" }
}
```
Mac/Linux: `~/.codeium/windsurf/mcp_config.json`
Windows: `%USERPROFILE%\.codeium\windsurf\mcp_config.json`
- [MCP setup for Windsurf](https://www.trendsmcp.ai/mcp-server-for-windsurf)

### VS Code
Use the Add to VS Code install button on docs, or paste into `.vscode/mcp.json` inside `servers` (Command Palette → `MCP: Add Server`):
```json
"trends-mcp": {
  "type": "http",
  "url": "https://api.trendsmcp.ai/mcp",
  "headers": { "Authorization": "Bearer YOUR_API_KEY" }
}
```
- [MCP setup for VS Code](https://www.trendsmcp.ai/mcp-server-for-vs-code)

### Cline (VS Code extension)
MCP Servers tab → Remote Server → paste URL and header
```json
"trends-mcp": {
  "url": "https://api.trendsmcp.ai/mcp",
  "headers": { "Authorization": "Bearer YOUR_API_KEY" }
}
```
- [MCP setup for Cline](https://www.trendsmcp.ai/mcp-server-for-cline)

### GitHub Copilot
VS Code Command Palette → MCP: Add Server → paste URL and header
- [MCP setup for GitHub Copilot](https://www.trendsmcp.ai/mcp-server-for-github-copilot)

### Raycast
Raycast Settings → Extensions → MCP → Add Server → HTTP → paste URL and header
- [MCP setup for Raycast](https://www.trendsmcp.ai/mcp-server-for-raycast)

### ChatGPT (OpenAI)
ChatGPT Settings → Connectors → Add custom connector → paste MCP URL (`https://api.trendsmcp.ai/mcp` with your key, or follow the setup page)
- [MCP setup for ChatGPT](https://www.trendsmcp.ai/mcp-server-for-chatgpt)

### n8n
HTTP Request node or MCP Community node → paste URL and Bearer token
- [Trends MCP with n8n](https://www.trendsmcp.ai/n8n-trends-mcp)

### Make (Integromat)
HTTP module → POST https://api.trendsmcp.ai/api → Authorization: Bearer YOUR_API_KEY
- [Trends MCP with Make](https://www.trendsmcp.ai/make-com-trend-automation)

### Zapier
Webhooks by Zapier → POST https://api.trendsmcp.ai/api → Authorization header
- [Trends MCP with Zapier](https://www.trendsmcp.ai/zapier-trend-workflows)

### LangChain
```python
from langchain_mcp_adapters.client import MultiServerMCPClient
client = MultiServerMCPClient({"trends-mcp": {"url": "https://api.trendsmcp.ai/mcp", "transport": "streamable_http", "headers": {"Authorization": "Bearer YOUR_API_KEY"}}})
```
- [Trends MCP with LangChain](https://www.trendsmcp.ai/langchain-trends-mcp)

## Authentication

- REST + most MCP clients: `Authorization: Bearer <key>` against `api.trendsmcp.ai`
- Claude.ai Connectors: OAuth 2.0 against `www.trendsmcp.ai/mcp` (consent flow; no Bearer key in connector config)
Never expose your API key in client-side code or public repositories.

## Pricing

| Plan | Monthly requests | Price |
| --- | --- | --- |
| Free | 100 / month | $0 |
| Starter | 1,000 / month | $19 / month |
| Pro | 5,000 / month | $49 / month |
| Business | 25,000 / month | $199 / month |

Annual billing saves 20%. Same sources on every plan. Details: [Pricing](https://www.trendsmcp.ai/pricing)

## What counts as a request

- `get_trends` / `get_time_series`: 1 source + keyword per call = 1 request
- `get_growth`: 1 source + keyword per call = 1 request (all `percent_growth` periods in that call included)
- `get_top_trends`: counted per feed (`type`) and per page (`limit`/`offset`)

## Data Sources

### Keyword sources — use with Get Trends & Get Growth

Pass the source value alongside keyword. On REST, set mode to "get_time_series" (time series) or "get_growth" (period-over-period %). Scores use a 0–100 index 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 subscribers                       | Subreddit name only, no r/ prefix                             |
| 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                                         |
| app downloads   | Android app downloads (AppBrain)            | Android bundle ID e.g. com.openai.chatgpt                     |
| app rankings    | Android app store ranking charts (AppBrain) | Android bundle ID e.g. com.himshers.hims                      |
| npm             | npm package weekly downloads                | Exact package name, case-sensitive e.g. react, @babel/core    |
| steam           | Steam concurrent players (monthly)          | Game display name e.g. Elden Ring (first Steam search result) |

### Live feeds — use with Get Top Trends (no keyword needed)

Pass the type value with mode: "get_top_trends". Returns the current ranked leaders on that platform. Feed labels are case-sensitive and must match exactly.

| 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                     |
| TikTok Trending Searches        | Top trending search terms on TikTok                 |
| TikTok Shop Hot Products        | Top hot products on TikTok Shop                     |
| 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                             |
| Steam Most Played               | Top games by concurrent live players                |
| GitHub Trending Repos           | Daily trending repositories across all languages    |
| IMDb MOVIEmeter                 | Top 100 most-popular movies by user activity        |
| Open Library Trending Books     | Daily trending books from Open Library              |

## API Reference

All requests go to POST https://api.trendsmcp.ai/api. Pick the operation with the mode field in the JSON body:

| mode               | What it returns                         | Required fields                                              |
|--------------------|-----------------------------------------|--------------------------------------------------------------|
| get_time_series    | ~5 years of weekly points for a keyword | source, keyword                                              |
| get_growth         | % change over one or more periods       | source, keyword (percent_growth optional, defaults to ["12M"]) |
| get_top_trends     | Live ranked leaderboard for a feed      | type (limit optional, default 25)                            |

get_trends is accepted as an alias for get_time_series on REST (same handler). Prefer get_time_series in REST examples. MCP tool name remains get_trends.

### get_time_series (REST) / get_trends (MCP)

Returns a full historical time series for a keyword from a single source. Approximately 5 years of weekly data. Specify one source per request.

Request body:
- mode (string, required): "get_time_series" (REST alias: "get_trends"; MCP tool: get_trends)
- source (string, required): one source per request
- keyword (string, required)

Response fields (array of data points):
- date (string): ISO 8601 e.g. "2026-03-21"
- value (number): trend score 0–100
- volume (number|null): absolute volume where available
- keyword (string)
- source (string)

Example:
```json
{"mode": "get_time_series", "source": "google search", "keyword": "bitcoin"}
```
```json
[{"date": "2026-03-21", "value": 47, "volume": 25853617, "keyword": "bitcoin", "source": "google search"}]
```

### get_growth (MCP + REST)

Calculates point-to-point percentage growth over one or more time windows. Supports preset strings or exact custom date pairs. Pass one source or a comma-separated list (e.g. "amazon, tiktok, youtube"). One request per source + keyword regardless of how many periods are in percent_growth.

Request body:
- mode (string, required): "get_growth"
- source (string, required): one source or comma-separated list
- keyword (string, required)
- percent_growth (array, optional): preset strings or custom date objects; defaults to ["12M"]

Growth period presets: 7D 14D 30D 1M 2M 3M 6M 9M 12M 1Y 18M 24M 2Y 36M 3Y 48M 60M 5Y MTD QTD YTD

Custom date range object: {"name": "optional label", "recent": "YYYY-MM-DD", "baseline": "YYYY-MM-DD"}

Response fields:
- search_term, data_source
- results (array, one per period): period, growth (%), direction, recent_date, baseline_date, recent_value, baseline_value, volume_available, recent_volume, baseline_volume, volume_growth
- metadata: total_data_points, calculations_completed, all_successful

Example:
```json
{"mode": "get_growth", "source": "google search", "keyword": "nike", "percent_growth": ["12M", "3M", "YTD"]}
```
```json
{
  "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 (MCP + REST)

Returns ranked items from live platform feeds. On REST, omit type to get all feeds in one response. On MCP, type is required (one feed per call).

Request body:
- mode (string, required): "get_top_trends"
- type (string): feed name — required for MCP, optional for REST
- category (string, optional): filter for Amazon Best Sellers by Category and Top Websites
- limit (integer, default 25): max items per feed, up to 200
- offset (integer, default 0): pagination

Example:
```json
{"mode": "get_top_trends", "type": "Google Trends", "limit": 10}
```
```json
{"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"]]}
```

## MCP Prompts — Example AI queries

Always include "using TrendsMCP" or "via TrendsMCP" so the AI routes to the MCP instead of a web search.

Get Trends:
- "Using TrendsMCP, show me the Google Search trend for nvidia over the past 5 years."
- "Via TrendsMCP, show me the download trend for Android app com.openai.chatgpt."
- "Using TrendsMCP, show me the YouTube and TikTok trend history for Stanley cup."
- "Via TrendsMCP, get the Wikipedia page view history for Bitcoin weekly."
- "Using TrendsMCP, show me the Amazon search trend for air fryer over 5 years."
- "Via TrendsMCP, pull the npm download trend for langchain weekly."
- "Using TrendsMCP, show me Steam concurrent player data for Elden Ring."
- "Via TrendsMCP, show the news volume trend for Tesla over the last year."
- "Using TrendsMCP, show subscriber history for subreddit wallstreetbets on Reddit."

Get Growth:
- "Using TrendsMCP, how has Google Search interest in GLP-1 grown over the past 12 months?"
- "Via TrendsMCP, show me 3M, 6M, and 1Y growth for Anthropic on Google Search."
- "Using TrendsMCP, what's the YTD Google Search growth for Duolingo?"
- "Via TrendsMCP, compare 6-month growth for weight loss drugs across Google, TikTok, and Amazon."
- "Using TrendsMCP, how has news sentiment for Meta changed over the past 6 months?"
- "Via TrendsMCP, show Google Search growth for AI agents from Jan 2025 to Jan 2026."
- "Via TrendsMCP, show me 12M Google Shopping growth for running shoes."

Get Top Trends:
- "Using TrendsMCP, what's trending on Google right now?"
- "Via TrendsMCP, show me the top TikTok trending hashtags today."
- "Using TrendsMCP, what are the hottest Reddit posts right now?"
- "Via TrendsMCP, what are the top trending Wikipedia articles today?"
- "Using TrendsMCP, show me what's trending on X right now."
- "Via TrendsMCP, what apps are topping the App Store Free charts today?"
- "Using TrendsMCP, what are the top-rated Amazon best sellers right now?"
- "Via TrendsMCP, show Amazon best sellers for category Electronics."
- "Via TrendsMCP, what's trending on YouTube right now?"

## Errors

| Status | Error code        | Meaning                                                               |
|--------|-------------------|-----------------------------------------------------------------------|
| 400    | missing_parameter | Required field missing from request body                              |
| 400    | invalid_source    | Unrecognized source value                                             |
| 401    |                   | Missing or invalid API key                                            |
| 404    | not_found         | No series matched this keyword/source                                 |
| varies | data_unavailable  | Pipeline could not return data (temporary gap or empty upstream)      |
| 429    | rate_limited      | Monthly request limit reached — upgrade for more                      |
| 500    | internal_error    | Unexpected server error                                               |

Error shape: {"error": "missing_parameter", "message": "The 'keyword' parameter is required."}