Trendzeist – Google Trends for content ideation

trendzeist-mcp

一次调用，将 Google Trends 转化为接下来 10 篇博客文章。

trendzeist-mcp 为你的 AI 助手提供按排名整理的爆发式增长／上升趋势／常青主题、人们实际提出的问题、AEO 机会发现器（根据趋势、新闻报道、Wikipedia 收录情况和可引用性提示对问题集群评分），以及热度曲线、地区需求、实时趋势、Google News 中报道某个主题的媒体和Wikipedia 关注度。免费、本地运行、保护隐私。无需 API 密钥、账户或浏览器。

SEO 和 AEO： 找出人们提出的问题，以及答案引擎回答的问题，然后让你的网站成为它们引用的来源。衡量你自己在 ChatGPT / Perplexity / AI Overviews 中的可见度不在本项目范围内；此服务告诉你写什么，而不是谁会引用你。

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) ..."

构建所用技术

trendzeist-mcp 是构建在 pytrends-modern 之上的轻量 MCP 层，由它处理所有 Google Trends 请求。Trendzeist 添加了 MCP 工具和提示词、请求限流、持久化磁盘缓存、严格的输入验证、便于大模型使用的 JSON 输出，以及按排名整理的 discover_topics 工作流。其他运行时依赖项：mcp（官方 MCP Python SDK）、pandas、platformdirs 和 requests。均采用 MIT/BSD/Apache 许可证。Google Autocomplete、Google News RSS 和 Wikimedia REST API 均通过 requests 直接调用（无需密钥）。

快速开始

# 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 — 在 claude_desktop_config.json 的 mcpServers 下添加 （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： 使用相同的 command/args 结构 — 请参阅 llms-install.md （该文件专为复制粘贴给 AI 助手、让它帮你完成安装而编写）。

工具

工具	内容
discover_topics	根据 1–5 个种子词提供排名靠前的博客主题：爆发 > 上升 > 常青，去重后每个主题都包含标题 angle 和可解释的 score；还包括人们会问的问题 questions[]，以及未纳入排名、疑似垃圾内容的上升查询 suspect[]。传入 site_queries（你的网站目前已有排名的查询），即可为每个主题标注 covered / partial / gap
mine_questions	从 Google Autocomplete 获取关于种子词的长尾问题（how to、why、what is、vs 等），去重并标注角度——可用于 FAQ / AEO
aeo_opportunities	按种子词 × 角度聚类问题，并结合种子词近期趋势（过去 12 个月的 direction_now、growth_3m）、Google News 报道情况（可引用 / 联系的出版商）、维基百科收录情况、你的网站覆盖情况（site_queries）和引用提示进行评分——一次调用即可获取，各数据源的部分故障不会影响其他来源
what_changed	查看自上次快照以来的变化（1–90 天）：新出现和晋升的爆发查询（立即调查）、新上升的查询（考虑采用）、降温 / 下滑的查询（更新现有文章，或复核——移除前先用 interest_over_time 验证）、排名变化和 direction_now 转向——数据来自本地观测档案
seasonality	需求每年的高峰时段（5 年的周度数据）：peak_months、seasonal_strength、next_peak、publish_by（提前 6 周）、一句话 insight
compare_channels	主题在哪些渠道增长：网页 / YouTube / 新闻 / 图片 / 购物，并提供 growth_3m、direction_now、fastest_channel、momentum（增长 / 持平 / 全面下滑）和 format_hint（视频教程、购买指南、借势新闻的文章等）
trend_history	本地档案中关于某个关键词的所有记录：first_seen、breakout_episodes（独立的一轮轮爆发；反复出现 = 持久主题页）与 breakout_observations（轮询次数）、每个时间范围的 direction_timeline、seen_under_seeds——免费，无需请求
news_coverage	Google News 中报道某个主题的媒体：标题、出版商频次表、近期性直方图、报道标签
wiki_attention	精确匹配标题的维基百科词条和每日页面浏览量（趋势方向、增长）；当只找到不同的搜索结果时，返回 has_article=false 和可选的 related_article
trendzeist_status	每个数据源的健康状态（运行中 / 错误 / 空闲）、缓存使用情况、观测档案（行数、日期、上次错误）、有效设置——免费，无需请求
interest_over_time	0–100 的关注度曲线，包含平均值、峰值、direction（整个时间范围）、direction_now（近期斜率）、growth_3m / growth_12m 和通俗易懂的 insight
compare_keywords	对 2–5 个关键词进行正面对比，给出份额和胜出者
related_queries	热门及上升中的相关搜索，附带爆发标记、角度和 questions[]
related_topics	热门及上升中的知识图谱主题（尽力而为）
interest_by_region	需求分布区域：COUNTRY（全球范围）、REGION（某个国家内）、CITY / DMA（美国或全球范围）
suggest_keywords	将词语消歧为 Google 实体（标题、类型、mid）
trending_now	当前热门趋势及新闻标题；topic_filter 仅保留提及你所给词语的趋势
list_categories	查找 Google Trends 类别 ID，以缩小任意查询的范围

提示词：blog_ideas_from_trends(topic, audience, geo)（引导式构思）、 content_brief(topic, audience, geo)（标题、大纲、FAQ、地区、出版商）、 answer_brief(question, geo)（可引用的答案：直接回答、统计数据、引文、来源、 FAQ、schema）和 weekly_review(seeds, geo, site_queries)（内容会议：立即发布 / 安排日期 / 更新 / 停用）。可直接使用的 Agent 技能见 SKILL.md。

输出约定

• 每个结果都包含 schema_version（当前为 3；仅在移除字段或字段含义发生变化时才会递增）以及 _meta，其中包含本次调用的 requests_made、cache_hit、cache_hits、cache_misses——让模型知道何时该放慢速度。仅当本地归档无法写入时才会出现 _meta.archive_error（工具结果不受影响）。
• 可解释的评分。 discover_topics.topics[] 和 aeo_opportunities.opportunities[] 包含 score（0-100）以及 score_breakdown，后者有五个组成部分，每项格式为 {points, max, reason}：demand 25（发现的问题或热门查询的受欢迎程度）、momentum 25（direction_now + 突破 / 上升趋势）、freshness 15（Google News；未获取时为 0）、gap 20（相对于 site_queries：缺口为 20 / 部分覆盖为 10 / 已覆盖为 0；没有这些数据时为中性值 10）、aeo 15（问题式查询；没有维基百科文章的定义类切入角度）。仅比较同一次调用中的评分。
• 观察归档。 每次获取新数据（非缓存命中）时，相关查询、趋势标签、热门搜索和挖掘出的问题都会形成一个快照（唯一 ID；Google 返回空结果也会形成快照），并将规范化后的行保存到磁盘缓存旁的 archive.sqlite3 中（使用标准库 sqlite3，保留 365 天，按需打开）。相关查询快照会保存完整列表，不受调用方 limit 的影响，因此比较时不会凭空产生下降记录。what_changed 和 trend_history 会读取归档；trendzeist_status.archive 会报告归档状态。疑似上升查询不会写入归档。归档出错不会导致工具调用失败。设置 TRENDZEIST_ARCHIVE=0 可关闭归档。
• 站点覆盖判断从严。 只有当 aeo_opportunities 中某个聚类里的每个问题都已覆盖时，该聚类才会标记为 covered；混合情况标记为 partial（见 coverage_counts），因此 exclude_covered 永远不会隐藏尚未回答的问题。
• angle 的值为 how-to | comparison | listicle | definition | news 之一（或 null）——即查询所提示的标题格式。请将其与证据配套使用：how-to → 步骤 + 数字，comparison → 表格 + 引述，definition → 引用一手来源，news → 带日期的发布方引述。
• 所有静默调整都会报告：被限制的上限会添加 note，空结果会添加 reason。
• 两种趋势标签。 direction 比较时间窗口的第一个三分之一和最后一个三分之一（rising | falling | stable | new | no_interest | insufficient_data；new = 第一个三分之一内没有关注度）。direction_now 比较窗口的最后四分之一与之前的四分之一，回答“它现在还在增长吗？”。在窗口中期达到峰值的话题会显示 direction: rising（或 new）和 direction_now: falling；insight 句子会说明这一点。组合工具（discover_topics、aeo_opportunities）始终会使用 today 12-m 获取种子趋势（并回显为 query.trend_timeframe），并依据 direction_now 评分。
• 疑似上升查询。 搜索操纵活动会给多个无关的“Breakout”查询附上同一个名称。related_queries 会将此类条目标记为 suspect: true，并添加 suspect_reason；discover_topics 会将它们移至 suspect[]；aeo_opportunities 会忽略它们。Google 的 is_breakout 值会保留，仅信任度会改变。
• citability_hints（位于 aeo_opportunities 中）体现了 GEO 论文（Aggarwal 等人，KDD 2024）的结论：引用来源、引述和统计数据均能使 AI 引擎可见度提升 30-40%；关键词堆砌则毫无作用。
• 语言随市场变化。 未设置 TRENDZEIST_HL 时，geo="BR" 会使用 hl=pt-BR 查询 Google（约映射 50 个国家/地区），因此相关查询会以葡萄牙语返回。实际使用的语言会回显为 query.hl。Google News 始终使用市场对应的版本（例如 BR:pt），即使 TRENDZEIST_HL 固定了 Trends 界面的语言。
• 权威渠道： 在任意探索工具中传入 gprop="news" 或 gprop="youtube"，即可查看新闻媒体和视频受众正在搜索什么——这些正是答案引擎最常引用的来源。gprop="images" 和 "froogle"（购物）也可用。

为什么选择它？

	trendzeist-mcp	典型替代方案
一次调用即可发现并排名主题	✅ discover_topics	❌ 仅提供原始基础功能
引导式创意提示词	✅ blog_ideas_from_trends	❌
多来源、无需密钥	✅ Trends + Autocomplete + News + Wikipedia	单一来源，或付费聚合服务
了解何时值得关注，以及什么值得做	✅ what_changed、seasonality、compare_channels、site_queries 缺口	❌ 仅提供数据，不提供编辑解读
相关查询 + 突增检测	✅	托管/付费服务中通常缺失
成本 / 身份验证	免费，无需身份验证	API 密钥，每月配额
是否需要浏览器	不需要	部分 Python 库需要 Chrome
客户端重启后缓存仍然保留	✅ 安全的 JSON 磁盘缓存	通常仅存于内存，或没有缓存
友好的速率限制	✅ 对每个 HTTP 请求进行限流	❌ 请求突发，频繁收到 429 错误

从源代码运行

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

将客户端指向克隆目录，使用 "command": "uv", "args": ["--directory", "/path/to/trendzeist-mcp", "run", "trendzeist-mcp"]。

配置（环境变量）

变量	默认值	含义
TRENDZEIST_HL	（未设置 → 遵循 geo）	固定 Trends/Autocomplete UI 语言（例如 en-US）；Google News 独立使用其国家/地区版本。未设置时，语言遵循 geo（BR → pt-BR，未知 → en-US）
TRENDZEIST_TZ	360	时区偏移（分钟）
TRENDZEIST_MIN_INTERVAL	2.0	每次向 Google 主机发送 HTTP 请求之间的最短间隔秒数（Trends cookie / token / 数据、RSS、Autocomplete、News）
TRENDZEIST_WIKI_MIN_INTERVAL	0.5	向 Wikimedia 发送请求之间的最短间隔秒数（与 Google 分开限流）
TRENDZEIST_EXPLORE_TTL	900	Trends 探索、News 搜索的缓存秒数
TRENDZEIST_RSS_TTL	300	趋势 RSS 源的缓存秒数
TRENDZEIST_STATIC_TTL	86400	类别、建议、Autocomplete、Wikipedia 的缓存秒数
TRENDZEIST_MAX_MEMORY_ENTRIES	256	内存缓存条目数（磁盘缓存无上限，过期时清理）
TRENDZEIST_MAX_SERIES_POINTS	60	将兴趣曲线降采样至不超过此点数（正整数）
TRENDZEIST_RETRIES	3	暂时性错误的重试次数
TRENDZEIST_BACKOFF	1.5	指数退避系数
TRENDZEIST_PROXIES	—	以逗号分隔的代理 URL。探索请求按请求轮换；RSS、Autocomplete、News 和 Wikipedia 始终使用第一个代理
TRENDZEIST_CACHE_DIR	OS 用户缓存目录	持久化 JSON 缓存位置（0700）；设为 off 可禁用（同时禁用存档）
TRENDZEIST_ARCHIVE	1	设为 0 可禁用观测存档（此时 what_changed / trend_history 会报告 available: false）
TRENDZEIST_ARCHIVE_DAYS	365	存档记录的保留天数（每个进程首次写入时清理一次）
TRENDZEIST_LOG_LEVEL	WARNING	Python 日志级别（stderr）

注意事项和限制

• Google 的请求速率限制很严格（HTTP 429）。所有 HTTP 请求都会串行发送并限流；结果会以纯 JSON 格式缓存在磁盘上（探索／新闻缓存 15 分钟，RSS 缓存 5 分钟，类别／Autocomplete／Wikipedia 缓存 24 小时），因此客户端重启后无需重新获取。内存缓存有大小上限，过期文件会自动清理。发生错误时会以工具错误的形式返回，并附带指导信息。
• mine_questions 每次未命中缓存时最多发送 16 个 Autocomplete 请求（每个问题前缀一个）；按默认的 2 秒间隔计算，最坏情况下约需 30 秒。达到 limit 后会立即停止；如果 Google 开始拒绝请求，则会返回部分结果。
• 数值是 Google 的相对 0–100 指数，并非绝对搜索量。growth_3m／growth_12m 会比较最近一个时间窗口与此前窗口的均值，因此每项都需要两个窗口的数据：growth_3m 需要至少 6 个月的数据（today 12-m），growth_12m 需要 today 5-y。如果因此导致其中任一值为 null，摘要会附带 growth_note，说明应使用哪个时间范围。
• Google 对会话开始时的第一波请求限制最严。在 discover_topics／aeo_opportunities 中，请从 1–2 个种子开始；趋势上下文步骤遇到 429 不再会导致整个调用中止（仍会获取相关查询），跳过提示会说明何时重试。
• mine_questions 中的问题前缀为英文；如果要针对非英语市场获取当地语言的问题，请传入一个已用该语言表述的种子。
• Google 经常不会返回 related_topics；related_queries 则可靠。
• Google 旧版的每日 trending_searches 端点已停用（404）；trending_now 使用 RSS feed。
• aeo_opportunities 是开销最高的调用：最坏情况下每个种子会发送 1 + 10 个请求（Wikipedia 使用独立通道）。Google 请求会在首次遇到 429 时停止；仍会返回 Wikipedia 数据。trendzeist_status 无需发送请求，即可显示哪个数据源出错。
• wiki_attention.has_article 仅确认是否匹配到完全相同标题的搜索结果；其他 Wikipedia 搜索结果会显示为 related_article，不能作为引文或内容缺失的证据。在声称存在百科内容缺口前，请手动核实相关标题和重定向。
• 缓存 TTL、内存条目数和序列点数上限必须为正整数；无效值会产生可操作的工具错误，而非不透明的格式化失败。
• what_changed 需要基线：首次调用会记录基线，并针对每个种子报告 reason: "baseline recorded <date>; rerun after <date>"。快照会在日常使用中累积（discover_topics、today 3-m 下的 related_queries，以及 today 12-m 下的趋势标签），因此正常工作一周就足够。trend_history 仅用于存档。
• seasonality 需要至少 3 年完整的非零每周数据（today 5-y）；较新的主题会返回 seasonal: null 和一个 reason。画像和强度只使用完整年份；淡季兴趣为零时，会将其报告为季节性，并附上 strength_note（比率无上限）；in_peak_now 表示峰值月份就是当前月份。compare_channels 会发送 5 个请求，并在首次遇到 429 时停止（skipped 会列出其余请求）；各渠道采用独立的 0–100 量表，而 momentum: all_declining 表示 fastest_channel 只是下降得最慢。
• what_changed 绝不会建议“停用”：退出 Google 的相对且有上限的相关结果列表，并不能证明需求在下降。条目会附带 review: ... 操作；停用前，请对该条目使用 interest_over_time 进行确认。如果某个快照中 Google 未返回任何结果，报告会如实说明，而不会将其描述为整体暴跌。
• 有意不使用 pytrends-modern 中的 Camoufox／浏览器模式。

免责声明

此服务会调用与 trends.google.com 前端相同的未公开端点（以及 Google Autocomplete 和 Google News RSS）。这些端点均为非官方接口，可能会变更、限制请求频率，或在不另行通知的情况下停止服务。CI 中每周都会运行一次 实时金丝雀测试，以尽早发现问题。 本项目与 Google LLC 无关联，也未获得其认可或赞助。 “Google Trends”是 Google LLC 的商标。您有责任遵守所在司法管辖区适用的 Google 服务条款。

贡献

欢迎提交问题和 PR。请阅读 AGENTS.md 了解架构和约定 （如果您要让编码 Agent 使用此代码库，这份文档也很有用）。在 Google 变更后修正数据格式，是最有价值的贡献——请附上您发起的调用及返回结果。

许可证

MIT——详见 LICENSE。基于 pytrends-modern 构建（MIT）。