{ "markdown": "# trendzeist-mcp\n\n\n\n**Turn Google Trends into your next 10 blog posts — in one call.**\n\ntrendzeist-mcp gives your AI assistant ranked **breakout / rising / evergreen** topics,\ninterest curves, related searches, regional demand and real-time trends. Free, local,\nprivate. No API key, no account, no browser.\n\n```\nYou: Give me blog post ideas about home espresso for US readers.\nAgent: → discover_topics([\"espresso\", \"espresso machine\"], geo=\"US\")\n ← 1 breakout, 14 rising, 14 evergreen candidates with growth %\n → compare_keywords([\"how to descale espresso machine\", \"best coffee beans for espresso\"])\n \"1. How to Descale Your Espresso Machine (rising +120%, publish now) ...\"\n```\n\n## Quick start\n\n```bash\n# any one of these\nuvx trendzeist-mcp\npipx run trendzeist-mcp\npip install trendzeist-mcp && trendzeist-mcp\ndocker run -i --rm ghcr.io/phalkmin/trendzeist-mcp\n```\n\n**Claude Desktop** — add under `mcpServers` in `claude_desktop_config.json`\n(macOS `~/Library/Application Support/Claude/`, Windows `%APPDATA%\\Claude\\`, Linux `~/.config/Claude/`):\n\n```json\n\"trendzeist\": { \"command\": \"uvx\", \"args\": [\"trendzeist-mcp\"] }\n```\n\n**Claude Code:** `claude mcp add trendzeist -- uvx trendzeist-mcp`\n**Cursor / VS Code / Codex:** same `command`/`args` shape — see [`llms-install.md`](llms-install.md)\n(written so you can paste it to an AI assistant and let it do the install).\n\n## Tools\n\n| Tool | What you get |\n|---|---|\n| `discover_topics` | Ranked blog topics from 1-5 seeds: breakout > rising > evergreen, deduped |\n| `interest_over_time` | 0-100 interest curve with mean, peak and direction |\n| `compare_keywords` | Head-to-head share and winner for 2-5 keywords |\n| `related_queries` | Top & rising related searches with breakout flags |\n| `related_topics` | Top & rising Knowledge-Graph topics (best-effort) |\n| `interest_by_region` | Where demand lives: COUNTRY / REGION / CITY / DMA |\n| `suggest_keywords` | Disambiguate a term into Google entities (title, type, mid) |\n| `trending_now` | What's trending right now, with news headlines |\n| `list_categories` | Find Google Trends category ids to narrow any query |\n\nPrompt: `blog_ideas_from_trends(topic, audience, geo)` — a guided ideation workflow.\n\n## Why this one?\n\n| | trendzeist-mcp | typical alternatives |\n|---|---|---|\n| Ranked topic discovery in one call | ✅ `discover_topics` | ❌ raw primitives only |\n| Guided ideation prompt | ✅ `blog_ideas_from_trends` | ❌ |\n| Related queries + breakout detection | ✅ | often missing in hosted/paid servers |\n| Cost / auth | free, none | API key, monthly quota |\n| Browser required | no | Chrome for some Python libraries |\n| Cache survives client restarts | ✅ safe JSON disk cache | usually in-memory or none |\n| Rate-limit friendly | ✅ throttled per HTTP request | ❌ bursts, frequent 429s |\n\n## Run from source\n\n```bash\ngit clone https://github.com/phalkmin/trendzeist-mcp && cd trendzeist-mcp\nuv sync --group dev\nuv run pytest -q # offline tests\nuv run pytest -q -m live # optional: live canary against Google\nuv run trendzeist-mcp # stdio server\nnpx @modelcontextprotocol/inspector uv run trendzeist-mcp # interactive debugging\n```\n\nPoint a client at the clone with\n`\"command\": \"uv\", \"args\": [\"--directory\", \"/path/to/trendzeist-mcp\", \"run\", \"trendzeist-mcp\"]`.\n\n## Configuration (env vars)\n\n| Variable | Default | Meaning |\n|---|---|---|\n| `TRENDZEIST_HL` | `en-US` | UI language for Google Trends |\n| `TRENDZEIST_TZ` | `360` | Timezone offset in minutes |\n| `TRENDZEIST_MIN_INTERVAL` | `2.0` | Minimum seconds between *every* HTTP request to Google (cookie, token, data, RSS) |\n| `TRENDZEIST_RETRIES` | `3` | Retry attempts on transient errors |\n| `TRENDZEIST_BACKOFF` | `1.5` | Exponential backoff factor |\n| `TRENDZEIST_PROXIES` | — | Comma-separated proxy URLs (rotated for explore calls; first one used for RSS) |\n| `TRENDZEIST_CACHE_DIR` | OS user cache dir | Persistent JSON cache location (`0700`); `off` to disable |\n| `TRENDZEIST_LOG_LEVEL` | `WARNING` | Python logging level (stderr) |\n\n## Notes & limitations\n\n- Google rate-limits aggressively (HTTP 429). Every HTTP request is serialised and\n throttled; results are cached (15 min explore, 5 min RSS, 24 h categories) as plain JSON\n on disk so client restarts don't re-fetch. Memory cache is bounded and expired files are\n swept automatically. Errors come back as tool errors with guidance.\n- Values are Google's relative 0–100 index, not absolute search volume.\n- `related_topics` frequently returns nothing from Google; `related_queries` is reliable.\n- Google's legacy daily `trending_searches` endpoint is gone (404); `trending_now` uses the RSS feed.\n- Camoufox/browser mode from pytrends-modern is intentionally not used.\n\n## Disclaimer\n\nThis server talks to the same undocumented endpoints the trends.google.com frontend uses.\nThey are unofficial and may change, rate-limit or disappear without notice. A weekly\n[live canary](.github/workflows/live-canary.yml) runs in CI to catch breakage early.\nThis project is not affiliated with, endorsed by, or sponsored by Google LLC.\n\"Google Trends\" is a trademark of Google LLC. You are responsible for complying with\nGoogle's terms of service in your jurisdiction.\n\n## Contributing\n\nIssues and PRs welcome. Read [`AGENTS.md`](AGENTS.md) for architecture and conventions\n(also useful if you point a coding agent at the repo). Data-shape corrections after a Google\nchange are the most valuable contribution — include the call you made and what came back.\n\n## License\n\nMIT — see [LICENSE](LICENSE). Built on [pytrends-modern](https://pypi.org/project/pytrends-modern/) (MIT).\n", "bytes": 5703, "sha": "7f8407f692dcb0353ffa12f841fac4e20f2ee9a4219facc6efbd6567bcbe00f4", "repo_slug": "phalkmin/trendzeist-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_phalkmin_trendzeist_mcp_e4556d2e/readme" }