{
  "markdown": "# Google Trends MCP\n\n[![npm](https://img.shields.io/npm/v/@den.dance/google-trends-mcp)](https://www.npmjs.com/package/@den.dance/google-trends-mcp)\n[![smithery badge](https://smithery.ai/badge/den-indance/google-trends-mcp)](https://smithery.ai/servers/den-indance/google-trends-mcp)\n[![GitHub](https://img.shields.io/badge/GitHub-den--indance%2Fgoogle--trends--mcp-181717?logo=github)](https://github.com/den-indance/google-trends-mcp)\n[![MIT License](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n\nThe Google Trends MCP server that actually works under Google's anti-bot. Connect Claude to live Google Trends data — keyword interest, related queries, regional popularity.\n\nMost Google Trends MCP packages crash with `Unexpected token 'l'` the moment Google blocks them (which is often). Free public proxy lists don't help — we tested 64 proxies from a popular \"high-quality\" list and 0 worked. This one uses your own rotating proxy with auto-retry, so blocked requests transparently retry on a fresh IP.\n\nBuilt by [Denys Malieiev](https://den.dance/).\n\n---\n\n## Why this one\n\n| What's fixed | Detail |\n|---|---|\n| Free public proxies don't work | We tested 64 — 0 survived. Bring your own rotating residential (Webshare/IPRoyal/Smartproxy free tier = ~46k requests on 1 GB) |\n| Auto-retry on Google blocks | When Google returns HTML, we retry up to 3 times with a fresh proxy from the pool. End-to-end success rate in our tests: 5/5 |\n| HTML-detection at the wrapper level | Other MCPs let `JSON.parse` crash with cryptic errors. We detect HTML before parsing |\n| Honest about what doesn't work | `get_trending_searches` is intentionally not exposed — Google blocks `dailyTrends`/`realTimeTrends` aggressively without residential proxies. We don't pretend otherwise |\n| Pool with fail-tracking | Proxies that fail 3 times get dropped automatically. Random rotation per request |\n| Per-request rotation | Each request picks a random proxy from the pool — Google can't accumulate per-IP rate limits |\n\n---\n\n## Quick Start\n\n```bash\nnpx @den.dance/google-trends-mcp\n```\n\nWorks out-of-the-box from non-flagged IPs, but Google rate-limits datacenter ranges aggressively. For reliable use, set up a proxy (see below).\n\n---\n\n## Setup\n\n### 1. Get a rotating proxy account\n\nRecommended (all have free tiers / pay-per-GB):\n- **Webshare** — free 1 GB residential (~46k Google Trends requests)\n- **IPRoyal** — $1.75/GB, lowest price\n- **Smartproxy / Decodo** — $4-7/GB, large pool\n- **Bright Data / Oxylabs** — $5-8/GB, enterprise grade\n\nMake sure the provider allows `*.google.com` in their ToS (most majors do).\n\n### 2. Configure Claude Desktop\n\nEdit your Claude Desktop config file:\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- **Linux**: `~/.config/Claude/claude_desktop_config.json`\n\nSingle rotating endpoint (recommended — provider rotates IPs internally):\n\n```json\n{\n  \"mcpServers\": {\n    \"google-trends\": {\n      \"command\": \"npx\",\n      \"args\": [\"@den.dance/google-trends-mcp\"],\n      \"env\": {\n        \"PROXY_URL\": \"http://USER:PASS@gate.smartproxy.com:7000\"\n      }\n    }\n  }\n}\n```\n\nOr an explicit list (useful for Webshare-style per-port proxies):\n\n```json\n{\n  \"mcpServers\": {\n    \"google-trends\": {\n      \"command\": \"npx\",\n      \"args\": [\"@den.dance/google-trends-mcp\"],\n      \"env\": {\n        \"PROXY_LIST\": \"http://user:pass@host1:6114,http://user:pass@host2:6014,http://user:pass@host3:5863\"\n      }\n    }\n  }\n}\n```\n\nFor longer lists, put proxies in a file (one per line, `#` comments allowed) and point to it:\n\n```json\n{\n  \"mcpServers\": {\n    \"google-trends\": {\n      \"command\": \"npx\",\n      \"args\": [\"@den.dance/google-trends-mcp\"],\n      \"env\": {\n        \"PROXY_LIST_FILE\": \"/home/you/.config/google-trends/proxies.txt\"\n      }\n    }\n  }\n}\n```\n\n```\n# ~/.config/google-trends/proxies.txt\nhttp://user:pass@host1:6114\nhttp://user:pass@host2:6014\nhttp://user:pass@host3:5863\n```\n\n`chmod 600` the file — credentials live there. Run `proxy_refresh` from Claude to hot-reload after editing.\n\nRestart Claude Desktop after saving the JSON config.\n\n### 3. Configure Claude Code\n\n```bash\nclaude mcp add google-trends \\\n  -e PROXY_URL=\"http://USER:PASS@gate.smartproxy.com:7000\" \\\n  -- npx @den.dance/google-trends-mcp\n```\n\n---\n\n## Environment Variables\n\n| Variable | Required | Description |\n|---|---|---|\n| `PROXY_URL` | recommended | Single rotating proxy endpoint. Provider handles IP rotation internally. No validation, no fallback |\n| `PROXY_LIST` | alternative | Comma-separated list of proxies (`http://user:pass@host:port,...`). Validated on startup, bad ones auto-dropped |\n| `PROXY_LIST_FILE` | alternative | Path to a file with one proxy per line (`#` comments and blank lines allowed). Validated on startup. Re-read on `proxy_refresh` |\n| `PROXIES_ENABLED` | no | Set to `false` to disable all proxy logic (direct requests). Default: enabled |\n\nPriority: `PROXY_URL` > `PROXY_LIST` > `PROXY_LIST_FILE`. If none are set, requests go direct (no proxy) — works only from non-flagged IPs.\n\n---\n\n## Tools\n\n### Data tools\n\n- `compare_keywords` — search interest over time for up to 5 keywords. Returns a timeline of relative scores.\n- `get_related_queries` — top + rising related queries for a keyword. Powered by Google's `relatedQueries` endpoint.\n- `get_interest_by_region` — top 20 regions by interest in a keyword.\n\n### Admin tools\n\n- `proxy_status` — show source (`single` / `env-list` / `env-file` / `none` / `disabled`), working count, age, freshness, validation progress.\n- `proxy_refresh` — force re-validation of the current proxy source. No-op in `PROXY_URL` mode.\n\n### Intentionally not exposed\n\n- `get_trending_searches` (daily / real-time trends) — Google blocks these endpoints aggressively. Even with residential proxies the success rate is too low to ship. We'd rather not lie about it.\n\n---\n\n## Known limitations\n\n- Google sometimes blocks multi-keyword requests (2 or 4 keywords) more aggressively than single. Our auto-retry handles this — but if all 3 attempts hit blocks, the request fails. Increase `MAX_ATTEMPTS` in `trends-client.js` if you need higher tolerance.\n- The underlying `google-trends-api` library scrapes Google's internal endpoints, which are undocumented and can change. If the library breaks, this MCP breaks too.\n- For very heavy use (>10k req/day) consider a managed service like SerpAPI or DataForSEO — at that scale the price difference vs your own proxy is marginal and the operational burden disappears.\n\n---\n\n## Example prompts for Claude\n\n- \"Compare search interest for 'claude ai', 'chatgpt', and 'gemini' over the last 12 months\"\n- \"What are people searching for related to 'sourdough bread'?\"\n- \"Which regions have highest interest in 'electric vehicle'?\"\n- \"Show me the proxy pool status\"\n\n---\n\n## Architecture notes\n\n- ~450 lines total across `server.js` (MCP handlers), `proxy-manager.js` (pool/cache), `trends-client.js` (retry logic with DI)\n- Validation: parallel workers (concurrency 50) check each proxy against `trends.google.com/api/autocomplete/test`, looking for the anti-XSSI prefix `)]}'` in the response\n- Cache: working proxies persisted to `proxies.json` (gitignored), keyed by SHA1 of input list — automatically invalidated when source changes\n- TTL: 4 hours; background re-validation when cache is stale\n- Fail tracking: proxies drop from rotation after 3 failures per session\n- Retry: every tool call retries up to 3 times with fresh `getAgent()` on HTML response or exception\n\n---\n\n## Development\n\n### Tests\n\n```bash\n# Unit only (fast, offline, no network)\nnpm test\n\n# With coverage report (html in coverage/)\nnpm run test:coverage\n\n# Integration (real Google hit, gated)\nRUN_INTEGRATION=1 npm run test:integration\n\n# E2E (spawns server.js, JSON-RPC over stdio)\nRUN_E2E=1 npm run test:e2e\n\n# Everything\nnpm run test:all\n```\n\n### Project structure\n\n- `server.js` — MCP server entrypoint (stdio transport)\n- `trends-client.js` — Google Trends API wrapper with retry-on-HTML\n- `proxy-manager.js` — proxy pool, validation, cache, source priority\n- `tests/unit/` — pure unit tests, no network (~40 tests, runs in ~2s)\n- `tests/integration/` — real Google endpoint tests (gated by `RUN_INTEGRATION=1`)\n- `tests/e2e/` — full MCP protocol tests via spawn (gated by `RUN_E2E=1`)\n\n---\n\n## Security\n\n- Never commit proxy credentials to version control. Use `PROXY_LIST_FILE` pointing to a `chmod 600` file outside the repo, or your secrets manager\n- `proxies.json` cache (built from validated proxies) is gitignored and never published — re-generated on first run after install\n\n---\n\n## License\n\nMIT",
  "bytes": 8670,
  "sha": "ba1bf2eaa45abe859c41d3948728bfac0e6cce9a4cb6865c4fbc0d12a9971e65",
  "repo_slug": "den-indance/google-trends-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_den_indance_google_trends_mcp_7ba3e94a/readme"
}