非官方 Google Trends MCP 服务器

⚠️ 非官方项目。 与 Google 无关联、未经 Google 认可或支持。Google Trends 没有公开可用的 API，因此该服务器读取的是 trends.google.com 网站使用的同一公开端点（通过 trendspy）——这意味着 Google 随时可能限流或使其失效，恕不另行通知。使用风险自负，在依赖它之前请阅读限制。

一个 Model Context Protocol 服务器，为 AI 助手——Claude、ChatGPT、Cursor 或任何 MCP 客户端——提供 Google Trends 数据访问：随时间变化的搜索兴趣、地区分布、热门搜索和关键词创意。

以远程 MCP 服务器（流式 HTTP）形式运行，专为 Google Cloud Run 设计——您在自己的 Google Cloud 项目中托管它，并将其连接到您选择的 AI 助手。也可通过 stdio 在本地运行。

连接到您的 AI 助手

部署后（参见设置），您将获得一个类似 https://<your-service>.run.app/<secret>/mcp 的端点 URL。所有工具均为只读。

Claude（网页/桌面）：设置 → 连接器 → 添加自定义连接器 → 粘贴 URL。适用于 Pro、Max、Team 和 Enterprise 套餐。

ChatGPT（网页）：启用开发者模式（设置 → 应用 → 高级设置），然后进入设置 → 应用 → 创建，将 URL 粘贴为 MCP 服务器端点，选择无身份验证（访问控制由 URL 中的密钥实现），点击扫描工具 → 创建。自定义 MCP 连接器需要付费套餐；在 Pro 套餐上，连接器仅限于只读工具——而该服务器恰好只有只读工具，因此可以正常工作。

Claude Code / Cursor / 其他 MCP 客户端：任何支持通过流式 HTTP 进行远程 MCP 的客户端均可使用，例如 claude mcp add --transport http google-trends <URL>。本地/stdio 设置请参见 docs/setup-advanced.md。

Related MCP server: Google Trends MCP Server

工作原理

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)

访问控制通过 URL 中的随机密钥路径段实现（部署时生成，存储在 gitignored 的 .mcp_secret 文件中）——这是因为大多数聊天客户端的自定义连接器界面（Claude、ChatGPT）无法发送认证头。Cloud Run 服务有意限制为单实例：一个实例 = 一个 IP 和一个共享缓存，这使 Google 的限流行为可预测。空闲时自动缩容到零，因此个人使用成本几乎为零。

工具

数据后端

数据层可替换（参见 backends/）：

• trendspy（默认）——使用 trendspy，它与 Trends 网站使用相同的非官方端点通信。免费，无需 API 密钥，但按 IP 限流，且如果 Google 更改端点可能会失效。

• official（占位）——用于 Google 官方 Trends API（alpha 版），该 API 需要应用审核。一旦 Google 授予您的项目访问权限，即可配置 backends/official_backend.py，然后设置 TRENDS_BACKEND=official。MCP 工具契约保持不变。

⚠️ Google Trends 的数值是相对搜索兴趣（每次查询内 0–100），而非绝对搜索量。

设置

两份指南，按需选择：

• 入门指南——从未使用过终端或 Google Cloud？从零开始的完整教程，约 15 分钟。

• 进阶指南——有经验？克隆 → ./deploy.sh → 连接；另含本地 stdio 模式、配置参考和架构说明。

部署到 Cloud Run（快速版）

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

脚本会启用所需 API、使用 Cloud Build 构建容器、以缩容到零的方式部署（低用量时几乎免费），并打印您的 MCP 端点：

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

随机 <secret> 路径段即访问令牌——服务在技术上是公开的，但没有完整 URL 就无法访问。请保密，如需轮换，请使用新密钥重新运行部署。

连接您的 AI 助手

Claude 和 ChatGPT 请参见上文连接到您的 AI 助手。Claude Code：

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

本地运行

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

配置

限制与已知问题

在依赖该服务器之前请阅读以下内容——这些是结构性问题，而非缺陷：

1. 非官方数据源。 没有公开的 Google Trends API（Google 的官方 API 为 alpha 版且仅限邀请）。该服务器使用网站自身的端点，Google 可随时更改或屏蔽。如果 Google 做出更改，服务器将无法工作，直到 trendspy 跟进——2025 年旧版 pytrends 库就遭遇了这种情况。

2. related_queries 和 related_topics 实际上已不可用。 Google 对这两个“小部件”端点针对自动化（非浏览器）客户端实施了近乎为零的配额。限制基于客户端指纹而非 IP——代理、VPN 和本地运行均无济于事。这些工具大多数情况下首次调用就会失败；错误信息会说明原因并指向 keyword_ideas（Google Autocomplete），这是关键词研究的可靠替代方案。

3. 其他所有端点的限流。 可用的端点（随时间变化的兴趣、按地区分布、热门趋势）也按 IP 限流。突发请求会触发 HTTP 429。服务器的缓解措施（见下文）使正常使用中很少遇到，但大量自动化查询会触及上限。

4. 相对值而非绝对量。 所有 Trends 数值均为每次查询内的 0–100（100 = 该词条组合/时间段/地区的峰值）。它们不是绝对搜索量，也不能跨查询比较。

5. 新鲜度权衡。 结果会被缓存（序列数据 12 小时、热门趋势 15 分钟、自动补全 24 小时）以保持在限流阈值以下——您可能会看到略有滞后的数据，这是设计使然。

6. 单实例。 部署时使用 --max-instances 1，因此适用于个人/小团队使用，而非高并发生产流量。

限流及服务器的应对设计

Google 对非官方 Trends 端点实施限流。服务器通过多层机制缓解：

• TTL 缓存——相同查询从内存中提供（序列数据约 12 小时、热门趋势 15 分钟、自动补全 24 小时），绝不会重复请求 Google。

• 间隔 + 串行化——每次仅一个上游调用，调用之间间隔 TRENDS_REQUEST_DELAY（默认 3 秒）。

• 重试 + 熔断器——遇到 429 时温和重试一次，然后进入冷却期（120 秒），期间新查询快速失败并显示清晰的“N 秒后重试”消息，而不是持续请求 Google。冷却期间缓存查询仍可正常使用。

• 通过 MCP 指令将使用规则推送给 AI 客户端：每次 interest_over_time 调用最多批量 5 个词条，规划调用而非随意发送，绝不自动重试限流错误。

• related_queries / related_topics 的现实：Google 已将这两个小部件端点对自动化（非浏览器）客户端的配额削减至近乎为零——这是基于指纹的，因此代理和 IP 变更无济于事。预期它们会失败；错误信息会解释原因。关键词研究请改用 keyword_ideas（Google Autocomplete）——它快速、可靠，且不受 Trends 配额限制。

部署脚本中的 --max-instances 1 是有意为之：一个实例 = 一个 IP 和一个共享缓存 = 可预测的限流行为。

用户提示

一次性请求比较（“比较 A vs B vs C 在 PT 地区 12 个月的趋势”→ 一次 API 调用），而不是逐词条查询。近期问题的重复查询免费（缓存）。如果遇到冷却消息，只需等待提示的秒数——不要反复重试。对于“人们围绕 X 搜索什么”，请请求关键词创意而非相关查询。

安全说明

本仓库中的所有内容均为通用内容——无凭据、密钥、项目 ID 或个人数据。有两项内容仅保存在您的本地机器上，绝不可提交：

• .mcp_secret——端点 URL 中的随机字符串。它是防止陌生人调用您已部署服务器的唯一屏障，请像对待密码一样对待它。deploy.sh 在首次运行时生成它并保存在此处，以便重新部署时复用相同的 URL。它已被 gitignore。（它与 GitHub 无关——它不是 GitHub 令牌，也无法访问您的账户。）

• 您的 Google Cloud 项目 ID——作为命令行参数传递给 deploy.sh，绝不会写入仓库中的任何文件。

轮换密钥（例如 URL 泄露时）：删除 .mcp_secret，重新运行 ./deploy.sh <PROJECT_ID>，并在 AI 助手的连接器设置中更新 URL。旧 URL 将立即失效。

首次推送前，请确认没有敏感内容被暂存：

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

免责声明

非官方社区项目；与 Google 无关联、未经 Google 认可或支持。“Google Trends”和“Google”是 Google LLC 的商标，此处仅用于描述软件所连接的服务。Trends 数据通过公开可访问的端点获取；您有责任按照 Google 的服务条款使用，风险自负。不提供任何形式的担保——端点可能随时停止工作。

许可证

MIT