Skip to main content

trendzeist-mcp

Turn Google Trends into your next 10 blog posts — in one call.

trendzeist-mcp gives your AI assistant ranked breakout / rising / evergreen topics, the questions people actually ask, an AEO opportunity finder that scores question clusters with trend, news coverage, Wikipedia presence and citability hints, plus interest curves, regional demand, real-time trends, who covers a topic in Google News and Wikipedia attention. Free, local, private. No API key, no account, no browser.

SEO and AEO: find the questions people ask — and answer engines answer — then make your site the source they cite. Measuring your own visibility inside ChatGPT / Perplexity / AI Overviews is out of scope; this server tells you what to write, not who cites you.

You:   Give me blog post ideas about home espresso for US readers.
Agent: → discover_topics(["espresso", "espresso machine"], geo="US")
       ← 1 breakout, 14 rising, 14 evergreen candidates with growth %, angles and 6 questions
       → mine_questions("espresso machine", geo="US")
       ← 30 long-tail questions: how-to 18, comparison 6, definition 4, listicle 2
       → compare_keywords(["how to descale espresso machine", "best coffee beans for espresso"])
       ← "Interest in 'how to descale espresso machine' rose 120% ... peaking 2026-08-30 (rising)."
       "1. How to Descale Your Espresso Machine (how-to, rising +120%, publish now) ..."

Built with

trendzeist-mcp is a thin MCP layer over pytrends-modern, which handles all Google Trends requests. Trendzeist adds the MCP tools and prompt, request throttling, a persistent disk cache, strict input validation, LLM-friendly JSON output and the ranked discover_topics workflow. Other runtime dependencies: mcp (official MCP Python SDK), pandas, platformdirs and requests. All MIT/BSD/Apache licensed. Google Autocomplete, Google News RSS and the Wikimedia REST API are called directly with requests (keyless).

Quick start

# any one of these
uvx trendzeist-mcp
pipx run trendzeist-mcp
pip install trendzeist-mcp && trendzeist-mcp
docker run -i --rm ghcr.io/phalkmin/trendzeist-mcp

Claude Desktop — add under mcpServers in claude_desktop_config.json (macOS ~/Library/Application Support/Claude/, Windows %APPDATA%\Claude\, Linux ~/.config/Claude/):

"trendzeist": { "command": "uvx", "args": ["trendzeist-mcp"] }

Claude Code: claude mcp add trendzeist -- uvx trendzeist-mcp Cursor / VS Code / Codex: same command/args shape — see llms-install.md (written so you can paste it to an AI assistant and let it do the install).

Tools

Tool What you get
discover_topics Ranked blog topics from 1-5 seeds: breakout > rising > evergreen, deduped, each with a title angle and an explainable score; plus questions[] people ask, suspect[] spam-like rising queries and filtered_out[] rising queries unrelated to the seeds, both kept out of the ranking. Pass site_queries (what your site already ranks for) to mark each topic covered / partial / gap; seeds that name several entities get ambiguous + clarify (ask before writing)
mine_questions Long-tail questions about a seed from Google Autocomplete (how to, why, what is, vs …, localised for pt / es / fr / de / it / pl / nl when geo or TRENDZEIST_HL says so — prefix_language tells which), deduped, angle-tagged and ranked by a realness score; bare prefix + seed padding goes to filtered_out[] — FAQ / AEO fuel
aeo_opportunities Question clusters per seed × angle, scored with the seed's recent trend (direction_now, growth_3m over 12 months), Google News coverage (publishers to quote / pitch), Wikipedia presence, your site's coverage (site_queries) and citability hints — one call, partial failures per source; seeds that name several entities get ambiguous + clarify (ask before writing)
what_changed What moved since your last snapshot (1-90 days): new and promoted breakouts (investigate now), new rising (consider), cooled / dropped queries (refresh existing post, or review — verify with interest_over_time before retiring), rank moves and a direction_now flip — from the local observation archive. First run: first_seen[] (current state, no history yet); no snapshot old enough: compares with the oldest and says its real age
seasonality When demand peaks each year (5-year weekly data): peak_months, seasonal_strength, next_peak, publish_by (6 weeks before), one-sentence insight
compare_channels Where a topic grows: web / YouTube / News / Images / Shopping with growth_3m, direction_now, fastest_channel, momentum (growing / flat / all_declining) and a format_hint (video tutorial, buying guide, newsjacking piece …)
trend_history Everything the local archive has seen about a keyword: first_seen, breakout_episodes (separate runs; recurring = durable page) vs breakout_observations (polling count), direction_timeline per timeframe, seen_under_seeds — free, no requests
recurring_topics Topics that keep breaking out in the local archive (≥ min_episodes separate runs in days, runs that overlap or restart within 7 days, under any seed, count once): episodes, first/last breakout, seeds, and the action one durable page, refreshed at each spike — free, no requests
news_coverage Who covers a topic in Google News: headlines, publisher frequency table, recency histogram, coverage label
wiki_attention Exact-title Wikipedia article and daily pageviews (direction, growth); has_article=false and optional related_article when only a different search hit is found
trendzeist_status Health of every source (live / error / idle), cache usage, observation archive (rows, dates, last error), effective settings — free, no requests
interest_over_time 0-100 interest curve with mean, peak, direction (whole window), direction_now (recent slope), growth_3m / growth_12m and a plain-English insight
compare_keywords Head-to-head share for 2-5 keywords, each with a role (leader, rising challenger, declining, niche, steady) and a content_implication; winner = the term to target (a rising challenger beats a falling leader; null + winner_reason when nothing has measurable interest) plus a one-line seo_interpretation
related_queries Top & rising related searches with breakout flags, angles and questions[]
related_topics Top & rising Knowledge-Graph topics (best-effort)
interest_by_region Where demand lives: COUNTRY (worldwide), REGION (within a country), CITY / DMA (US or worldwide)
suggest_keywords Disambiguate a term into Google entities (title, type, mid)
trending_now What's trending right now, with news headlines; topic_filter keeps only trends mentioning your words
list_categories Find Google Trends category ids to narrow any query

Prompts: blog_ideas_from_trends(topic, audience, geo) (guided ideation), content_brief(topic, audience, geo) (titles, outline, FAQ, regions, publishers), answer_brief(question, geo) (a citable answer: direct answer, statistic, quote, sources, FAQ, schema) and weekly_review(seeds, geo, site_queries) (content meeting: publish now / plan for a date / refresh / retire). A ready-made agent skill lives in SKILL.md.

Output conventions

  • Every result carries schema_version (currently 3; bumped only when a field is removed or changes meaning) and _meta with requests_made, cache_hit, cache_hits, cache_misses for that call — so the model knows when to slow down. _meta.archive_error appears only when the local archive could not be written (the tool result is unaffected).
  • Explainable score. discover_topics.topics[] and aeo_opportunities.opportunities[] carry score (0-100) and score_breakdown with five components, each {points, max, reason}: demand 25 (questions found or top-query popularity), momentum 25 (direction_now + breakout / rising), freshness 15 (Google News, 0 when not fetched), gap 20 (vs. site_queries: gap 20 / partial 10 / covered 0; neutral 10 without them), aeo 15 (question-shaped; definition angle with no Wikipedia article). Compare scores within one call only.
  • Observation archive. Every fresh fetch (not cache hits) of related queries, trend labels, trending searches and mined questions becomes one snapshot (unique id; an empty Google answer is a snapshot too) with normalised rows in archive.sqlite3 next to the disk cache (stdlib sqlite3, 365-day retention, opened lazily). Related-query snapshots hold the complete lists regardless of a caller's limit, so comparisons never invent drops. what_changed, trend_history and recurring_topics read it; trendzeist_status.archive reports it. Suspect rising queries never enter it. Archive errors never fail a tool. TRENDZEIST_ARCHIVE=0 turns it off.
  • Site coverage is conservative but not literal. An aeo_opportunities cluster is covered only when every question in it is covered; a mix is partial (see coverage_counts), so exclude_covered can never hide an unanswered question. Tokens are compared after plural folding and a small tech synonym map (mac/macos, wp/wordpress, js/javascript …), so "claude code mac" is covered by a site query "claude code macos"; matched names the site query behind each verdict. Prefixes only match on 6-letter stems ("code" is not "codex"), and a one-word head term inside a longer site query ("claude" in "claude code macos") is partial, not covered. Feeding the raw Search Console variants still helps.
  • angle is one of how-to | comparison | listicle | definition | verdict | news (or null) — the title format the query suggests. Pair it with evidence: how-to → steps + numbers, comparison → table + quotes, definition → cite a primary source, verdict (yes/no questions: "is it worth it", "does it work") → the verdict first, the deciding evidence, then caveats, news → dated publisher quotes.
  • Anything silently adjusted is reported: clamped limits add a note, empty results add a reason.
  • Two trend labels. direction compares the first and last third of the window (rising | falling | stable | new | no_interest | insufficient_data; new = no interest in the first third). direction_now compares the last quarter of the window with the quarter before it and answers "is it still growing now?". A topic that peaked mid-window reads direction: rising (or new) and direction_now: falling; the insight sentence says so. Composites (discover_topics, aeo_opportunities) always fetch the seed trend on today 12-m (echoed as query.trend_timeframe) and score on direction_now.
  • Suspect rising queries. Search-manipulation campaigns attach one name to many unrelated "Breakout" queries. related_queries flags such items suspect: true with a suspect_reason (a flagged .com also flags the queries carrying its name as words); discover_topics moves them to suspect[]; aeo_opportunities ignores them. Google's is_breakout value is kept, only the trust changes.
  • Off-topic related queries. Under niche seeds Google lists unrelated searches ("how to bake a cake" under an AI-tool seed) as breakouts from a tiny base and at values 0-3 in the top list. A breakout, or a top query below 10, that shares no word with the seed, the call's other seeds or the seed's on-topic top queries is off_topic: true (exact words after plural folding; generic words like make, work, best, github don't count). discover_topics moves them to filtered_out[] (list, reason, growth or popularity) and out of topics, questions and the score, with a note suggesting category= from two items; aeo_opportunities lists them in off_topic_dropped; related_queries flags them and keeps them out of questions. Measured risers ("moka pot" +300 %) are never flagged. They do not enter the archive, and what_changed re-applies the rules to older snapshots (baseline_filtered).
  • Level shifts are flagged. A sustained step (4-week mean changes ≥ 30 % and stays) appears in the summary as level_shifts[] (each with date, change_pct, post_shift_change_pct, growth_affected, shared) and level_shift (the largest). interest_over_time / compare_keywords add warnings[]: a step shared by two or more keywords in one week is likely_artifact (a Google sampling change; on 2026-07-12 five unrelated series stepped down 30-50 % at once). A flattened warning means joint normalisation squashed a small keyword: fetch it alone. Growth and direction figures spanning a step overstate the change; read the curve on each side.
  • "popularity unknown" in score_breakdown.demand is normal for rising-only items: Google gives a growth % but no popularity for them, so demand gets the minimum points. A top item rising from a very low base deserves a look at its curve (interest_over_time) before it becomes a post.
  • citability_hints (on aeo_opportunities) encode the GEO paper (Aggarwal et al., KDD 2024): citing sources, quotations and statistics each lifted AI-engine visibility 30-40%; keyword stuffing did nothing.
  • Language follows the market. With TRENDZEIST_HL unset, geo="BR" queries Google with hl=pt-BR (≈50 countries mapped), so related queries come back in Portuguese. The effective language is echoed as query.hl. Google News always uses the market's mapped edition (e.g. BR:pt), even when TRENDZEIST_HL pins the Trends UI language.
  • Authority channels: pass gprop="news" or gprop="youtube" to any explore tool to see what news outlets and video audiences are searching for — the sources answer engines cite most. gprop="images" and "froogle" (Shopping) also work.

Why this one?

trendzeist-mcp typical alternatives
Ranked topic discovery in one call ✅ discover_topics ❌ raw primitives only
Guided ideation prompt ✅ blog_ideas_from_trends ❌
Multi-source, keyless ✅ Trends + Autocomplete + News + Wikipedia single source, or paid aggregators
Knows when and what's worth it ✅ what_changed, seasonality, compare_channels, site_queries gaps ❌ data only, no editorial reading
Related queries + breakout detection ✅ often missing in hosted/paid servers
Cost / auth free, none API key, monthly quota
Browser required no Chrome for some Python libraries
Cache survives client restarts ✅ safe JSON disk cache usually in-memory or none
Rate-limit friendly ✅ throttled per HTTP request ❌ bursts, frequent 429s

Run from source

git clone https://github.com/phalkmin/trendzeist-mcp && cd trendzeist-mcp
uv sync --group dev
uv run pytest -q                 # offline tests
uv run pytest -q -m live         # optional: live canary against Google
uv run trendzeist-mcp              # stdio server
npx @modelcontextprotocol/inspector uv run trendzeist-mcp   # interactive debugging

Point a client at the clone with "command": "uv", "args": ["--directory", "/path/to/trendzeist-mcp", "run", "trendzeist-mcp"].

Configuration (env vars)

Variable Default Meaning
TRENDZEIST_HL (unset → follows geo) Pin the Trends/Autocomplete UI language (e.g. en-US); Google News uses its country edition independently. When unset, language follows geo (BR → pt-BR, unknown → en-US)
TRENDZEIST_TZ 360 Timezone offset in minutes
TRENDZEIST_MIN_INTERVAL 2.0 Minimum seconds between every HTTP request to Google hosts (Trends cookie / token / data, RSS, Autocomplete, News)
TRENDZEIST_WIKI_MIN_INTERVAL 0.5 Minimum seconds between Wikimedia requests (separate lane from Google)
TRENDZEIST_EXPLORE_TTL 900 Cache seconds for Trends explore, News search
TRENDZEIST_RSS_TTL 300 Cache seconds for the trending RSS feed
TRENDZEIST_STATIC_TTL 86400 Cache seconds for categories, suggestions, Autocomplete, Wikipedia
TRENDZEIST_MAX_MEMORY_ENTRIES 256 In-memory cache entries (disk is unbounded, swept on expiry)
TRENDZEIST_MAX_SERIES_POINTS 60 Downsample interest curves to at most this many points (positive integer)
TRENDZEIST_RETRIES 3 Retry attempts on transient errors
TRENDZEIST_BACKOFF 1.5 Exponential backoff factor
TRENDZEIST_JITTER 0.5 Random extra spacing between requests, as a fraction of the lane interval (0.5 → up to +50 %; never below the minimum)
TRENDZEIST_COOLDOWN 60 Seconds a source refuses uncached requests after an HTTP 429 (fail fast with retry_after); a Retry-After header wins when the 429 is seen directly (RSS, Autocomplete, News, Trends cookie), capped at 600; 0 disables
TRENDZEIST_STALE_FALLBACK 1 Serve an expired cache entry (kept 7 days past expiry) when a fetch is rate limited, flagged stale {age_days}; 0 disables
TRENDZEIST_PROXIES — Comma-separated proxy URLs. Rotated per request for explore calls; RSS, Autocomplete, News and Wikipedia always use the first one
TRENDZEIST_CACHE_DIR OS user cache dir Persistent JSON cache location (0700); off to disable (also disables the archive)
TRENDZEIST_ARCHIVE 1 0 disables the observation archive (what_changed / trend_history / recurring_topics then report a reason)
TRENDZEIST_ARCHIVE_DAYS 365 Retention for archive rows (pruned once per process on first write)
TRENDZEIST_LOG_LEVEL WARNING Python logging level (stderr)

Notes & limitations

  • Google rate-limits aggressively (HTTP 429). Every HTTP request is serialised and throttled; results are cached (15 min explore / News, 5 min RSS, 24 h categories / Autocomplete / Wikipedia) as plain JSON on disk so client restarts don't re-fetch. Memory cache is bounded and expired files are swept automatically. Errors come back as tool errors with guidance.
  • mine_questions issues up to 16 Autocomplete requests per uncached call (one per question prefix); at the default 2 s interval that is ~30 s worst case. It stops as soon as limit is met and returns partial results if Google starts refusing.
  • Values are Google's relative 0–100 index, not absolute search volume. growth_3m / growth_12m compare the mean of the last window with the window before it, so each needs two windows of data: growth_3m needs ≥ 6 months (today 12-m), growth_12m needs today 5-y. When either is null for that reason the summary carries a growth_note saying which timeframe to use.
  • Google rate-limits the first burst of a session hardest. Start with 1–2 seeds in discover_topics / aeo_opportunities; a 429 on the trend-context step no longer aborts the call (related queries are still fetched), and skip messages say when to retry.
  • mine_questions prefixes follow the request language (hl, from geo unless TRENDZEIST_HL pins it): tables exist for pt, es, fr, de, it, pl and nl, and prefix_language names the one used (aeo_opportunities mines with the same set). For other languages the English set is used and language_note says so; pass a seed already phrased in the market's language. The verb-based realness points are English-only, so abroad only the literal prefix + seed echo is filtered as padding.
  • After an HTTP 429 a source cools down (TRENDZEIST_COOLDOWN, default 60 s, or Google's Retry-After): uncached requests to it fail fast with a retryable error that says when to retry, trendzeist_status.sources[] shows cooling_down / retry_after_s, and every result carries _meta.rate_limited[] while any source is cooling. Other sources keep working. If the cache holds an expired copy of the refused query (kept 7 days), it is served and the result carries a top-level stale {age_days, note} (TRENDZEIST_STALE_FALLBACK=0 turns that off). interest_over_time / compare_keywords are one request for all keywords, so a 429 there has no per-keyword partial result; discover_topics / aeo_opportunities report per-seed errors and skipped.
  • related_topics frequently returns nothing from Google; related_queries is reliable.
  • Google's legacy daily trending_searches endpoint is gone (404); trending_now uses the RSS feed.
  • aeo_opportunities is the most expensive call: worst case 1 + 11 requests per seed (Wikipedia runs on its own lane). Google requests stop at the first 429; Wikipedia data is still returned. trendzeist_status shows which source is erroring without any request.
  • The ambiguous-seed check in discover_topics / aeo_opportunities is one extra Google Trends request per seed the first time that seed is seen (cached for the static TTL, so repeats are free). It is skipped once a call is rate limited (the seed report then carries an ambiguity_note); a failure there is an entities:<seed> error and never stops the seed. The lookup answers in the server language (TRENDZEIST_HL, default en-US), not the geo's: a Portuguese or German seed is rarely matched against English entity titles, so a non-English geo with no match gets an ambiguity_note saying so. Set TRENDZEIST_HL to the seed's language to check it properly.
  • wiki_attention.has_article confirms an exact-title search match only; a different Wikipedia search hit appears as related_article, not as a citation or proof of a gap. Verify related titles and redirects manually before claiming an encyclopedic content gap.
  • Cache TTLs, memory-entry count and series-point cap must be positive integers; invalid values produce an actionable tool error rather than an opaque formatter failure.
  • what_changed needs a baseline: the first call records one and reports reason: "baseline recorded <date>; rerun after <date>" per seed, together with first_run: true and first_seen[] (the current breakouts and rising queries, action "… (no history yet)"). When snapshots exist but none is since_days old, it compares with the oldest and says so (baseline_note, baseline_age_days). Snapshots accrue from everyday use (discover_topics, related_queries on today 3-m; trend labels on today 12-m), so a week of normal work is enough. trend_history and recurring_topics are archive-only; their episode counts can only separate two breakouts when a poll between them saw the topic not breaking out, so sparse polling undercounts (weekly what_changed runs are what makes them useful).
  • seasonality needs at least 3 full years of non-zero weekly data (today 5-y); younger topics return seasonal: null with a reason (for a two-year-old topic, read the shape with interest_over_time(..., "today 5-y") instead). Profile and strength use full years only; zero off-season interest is reported as seasonal with strength_note (ratio unbounded); in_peak_now flags that the peak month is the current one. compare_channels issues 5 requests and stops at the first 429 (skipped lists the rest); channels are separate 0-100 scales, and momentum: all_declining means fastest_channel is only falling least.
  • what_changed never says "retire": leaving Google's relative, bounded related list is not evidence of falling demand. Items get review: ... actions; confirm with interest_over_time on the item before retiring. A snapshot where Google returned nothing is reported as such, not as a mass drop.
  • Camoufox/browser mode from pytrends-modern is intentionally not used.

Disclaimer

This server talks to the same undocumented endpoints the trends.google.com frontend uses (plus Google Autocomplete and Google News RSS). They are unofficial and may change, rate-limit or disappear without notice. A weekly live canary runs in CI to catch breakage early. This project is not affiliated with, endorsed by, or sponsored by Google LLC. "Google Trends" is a trademark of Google LLC. You are responsible for complying with Google's terms of service in your jurisdiction.

Contributing

Issues and PRs welcome. Read AGENTS.md for architecture and conventions (also useful if you point a coding agent at the repo). Data-shape corrections after a Google change are the most valuable contribution — include the call you made and what came back.

License

MIT — see LICENSE. Built on pytrends-modern (MIT).

Metadata

Release files for trendzeist-mcp 0.6.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for trendzeist-mcp 0.6.1
File Size Uploaded Provenance Actions
trendzeist_mcp-0.6.1.tar.gz 160.0 kB With provenance Details for trendzeist_mcp-0.6.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for trendzeist-mcp 0.6.1
File Interpreter ABI Platform Actions
trendzeist_mcp-0.6.1-py3-none-any.whl Python 3 none any Details for trendzeist_mcp-0.6.1-py3-none-any.whl

Total release size: 261.0 kB

Release files / trendzeist_mcp-0.6.1.tar.gz

Download URL trendzeist_mcp-0.6.1.tar.gz
Size 160.0 kB
Tags Source
SHA-256 checksum
How to use checksums
7511e628f762226176f63e4b5b9df8cc549f9140ea2f92b8025b60acd9b55e03
BLAKE2b-256 checksum
How to use checksums
e4e1e89455e53f25a5791559f8f749973e56c1401bd54b620382684804f754ea
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

Release files / trendzeist_mcp-0.6.1-py3-none-any.whl

Download URL trendzeist_mcp-0.6.1-py3-none-any.whl
Size 101.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5172a8e77b86dd45cdc81baaf0dfc5628f6bf34863ee85c27eeda73019dbcd13
BLAKE2b-256 checksum
How to use checksums
1f9b45caa688c6796d45ee3aa3141c5ac62f412d243ba3345a3a3ec4082c872c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

Security for trendzeist-mcp 0.6.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for trendzeist_mcp-0.6.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 4, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page