Unofficial Google Trends MCP Server

Unofficial Google Trends MCP Server

⚠️ Unofficial project. Not affiliated with, endorsed by, or supported by Google. Google Trends has no generally available public API, so this server reads the same publicly accessible endpoints the trends.google.com website uses (via trendspy) — which means Google can rate-limit or break it at any time, without notice. Use at your own risk and read Limitations before relying on it.

A Model Context Protocol server that gives AI assistants — Claude, ChatGPT, Cursor, or any MCP client — access to Google Trends data: search interest over time, regional breakdowns, trending searches, and keyword ideas.

Runs as a remote MCP server (streamable HTTP) designed for Google Cloud Run — you host it in your own Google Cloud project and connect it to your AI assistant of choice. Also works locally via stdio.

Connect it to your AI assistant

After deploying (see Setup), you'll have an endpoint URL like https://<your-service>.run.app/<secret>/mcp. All tools are read-only.

Claude (web/desktop): Settings → Connectors → Add custom connector → paste the URL. Works on Pro, Max, Team, and Enterprise plans.

ChatGPT (web): enable Developer mode (Settings → Apps → Advanced settings), then Settings → Apps → Create, paste the URL as the MCP server endpoint, choose No authentication (access control is the secret in the URL), click Scan tools → Create. Custom MCP connectors require a paid plan; on Pro, connectors are limited to read-only tools — which is all this server has, so it works.

Claude Code / Cursor / other MCP clients: any client that supports remote MCP over streamable HTTP works, e.g. claude mcp add --transport http google-trends <URL>. For local/stdio setups see docs/setup-advanced.md.

How it works

AI assistant (Claude · ChatGPT · Cursor · any MCP client)
   │  MCP over streamable HTTP, at https://<cloud-run-url>/<secret>/mcp
   ▼
server.py — FastMCP tool layer (stateless, JSON responses)
   │  TrendsBackend interface (swappable, see backends/)
   ▼
backends/trendspy_backend.py
   │  1. TTL cache — identical queries answered from memory
   │     (12 h series · 15 min trending · 24 h autocomplete)
   │  2. Circuit breaker — after a 429: cooldown, fail fast with
   │     a clear "retry in Ns" message (no hammering Google)
   │  3. One upstream call at a time, ≥3 s apart
   ▼
Google's public endpoints
   ├─ trends.google.com (unofficial, same as the website uses)
   └─ suggestqueries.google.com (Autocomplete, for keyword_ideas)

Access control is a random secret path segment in the URL (generated at deploy, stored in a gitignored .mcp_secret file) — used because most chat clients' custom-connector UIs (Claude, ChatGPT) can't send auth headers. The Cloud Run service is capped at one instance on purpose: one instance = one IP and one shared cache, which keeps Google's rate limiting predictable. It scales to zero when idle, so hosting is ~free at personal usage.

Tools

Data backends

The data layer is swappable (see backends/):

• trendspy (default) — uses trendspy, which talks to the same unofficial endpoints as the Trends website. Free, no API key, but rate-limited per IP and could break if Google changes their endpoints.
• official (stub) — for Google's official Trends API (alpha), which is application-gated. Wire up backends/official_backend.py once Google grants your project access, then set TRENDS_BACKEND=official. The MCP tool contract stays identical.

⚠️ Values from Google Trends are relative search interest (0–100 within each query), not absolute search volumes.

Setup

Two guides, pick your speed:

• Beginner guide — never used a terminal or Google Cloud? Full walkthrough from zero, ~15 minutes.
• Advanced guide — experienced? Clone → ./deploy.sh → connect; plus local stdio mode, config reference, and architecture notes.

Deploy to Cloud Run (quick version)

gcloud auth login
./deploy.sh YOUR_PROJECT_ID europe-west1

The script enables the required APIs, builds the container with Cloud Build, deploys with scale-to-zero (≈ free at low usage), and prints your MCP endpoint:

https://google-trends-mcp-xxxxx.a.run.app/<secret>/mcp

The random <secret> path segment is the access token — the service is technically public, but unreachable without the full URL. Keep it private, and re-run the deploy with a new secret to rotate it.

Connect your AI assistant

See Connect it to your AI assistant above for Claude and ChatGPT. Claude Code:

claude mcp add --transport http google-trends https://google-trends-mcp-xxxxx.a.run.app/<secret>/mcp

Run locally

pip install -r requirements.txt
python server.py
# MCP endpoint at http://localhost:8080/mcp

Configuration

Limitations & known issues

Read this before relying on the server — these are structural, not bugs:

1. Unofficial data source. There is no public Google Trends API (Google's official API is alpha and invite-only). This server uses the website's own endpoints, which Google can change or block at any time. If Google changes something, the server breaks until trendspy catches up — exactly what happened to the older pytrends library in 2025.
2. related_queries and related_topics are effectively dead. Google enforces a near-zero quota on these two "widget" endpoints for automated (non-browser) clients. The limit is per client fingerprint, not per IP — proxies, VPNs, and running locally do not help. Expect these tools to fail on the first call most of the time; the error message says so and points to keyword_ideas (Google Autocomplete), which is the reliable alternative for keyword research.
3. Rate limits on everything else. The working endpoints (interest over time, by region, trending) are also rate-limited per IP. Bursts of requests trigger HTTP 429s. The server's mitigations (below) make this rare in normal use, but heavy automated querying will hit the wall.
4. Relative values, not volumes. All Trends numbers are 0–100 within each query (100 = the peak for that term set/period/geo). They are not absolute search volumes and are not comparable across separate queries.
5. Freshness trade-off. Results are cached (12 h for series data, 15 min for trending, 24 h for autocomplete) to stay under the rate limits — you may see slightly stale data by design.
6. Single instance. Deployed with --max-instances 1, so this is for personal/small-team use, not high-concurrency production traffic.

Rate limits & how the server is designed around them

Google rate-limits the unofficial Trends endpoints. The server mitigates this in layers:

• TTL cache — identical queries are served from memory (~12h for series data, 15 min for trending, 24h for autocomplete) and never hit Google twice.
• Spacing + serialization — one upstream call at a time, with a TRENDS_REQUEST_DELAY pause (default 3s) between calls.
• Retry + circuit breaker — one gentle retry on a 429, then a cooldown (120s) during which new queries fail fast with a clear "retry in Ns" message instead of hammering Google. Cached queries keep working during cooldowns.
• Usage rules pushed to the AI client via MCP instructions: batch up to 5 terms per interest_over_time call, plan calls instead of spraying them, never auto-retry a rate-limit error.
• related_queries / related_topics reality: Google has cut these two widget endpoints to near-zero quota for automated (non-browser) clients — this is per-fingerprint, so proxies and IP changes don't help. Expect them to fail; the error explains this. Use keyword_ideas (Google Autocomplete) for keyword research instead — it's fast, reliable, and not Trends-quota bound.

--max-instances 1 in the deploy script is intentional: one instance = one IP and one shared cache = predictable rate limiting.

Tips for users

Ask for comparisons in one go ("compare A vs B vs C in PT over 12 months" → one API call) rather than one term at a time. Repeats of recent questions are free (cache). If you hit a cooldown message, just wait the indicated seconds — don't spam retries. For "what do people search around X", ask for keyword ideas rather than related queries.

Security notes

Everything in this repo is generic — no credentials, keys, project IDs, or personal data. Two things stay local to your machine and must never be committed:

• .mcp_secret — the random string in your endpoint URL. It is the only thing preventing strangers from calling your deployed server, so treat it like a password. deploy.sh generates it on first run and keeps it here so redeploys reuse the same URL. It is gitignored. (It is unrelated to GitHub — it is not a GitHub token and has no access to your account.)
• Your Google Cloud project ID — passed as a command-line argument to deploy.sh, never written into any file in the repo.

To rotate the secret (e.g. if the URL leaked): delete .mcp_secret, re-run ./deploy.sh <PROJECT_ID>, and update the URL in your AI assistant's connector settings. The old URL stops working immediately.

Before your first push, confirm nothing sensitive is staged:

git status --short          # .mcp_secret and .env must NOT appear
git check-ignore -v .mcp_secret

Disclaimer

Unofficial community project; not affiliated with, endorsed by, or supported by Google. "Google Trends" and "Google" are trademarks of Google LLC, used here only to describe what the software connects to. Trends data is fetched via publicly accessible endpoints; you are responsible for using it in line with Google's terms of service and at your own risk. No warranty of any kind — endpoints can stop working at any time.

License

MIT