google-trends-mcp

Google Trends MCP

一个真正能在 Google 反机器人机制下正常运行的 Google Trends MCP 服务。将 Claude 连接到实时 Google Trends 数据，获取关键词热度、相关查询和地区受欢迎程度。

大多数 Google Trends MCP 程序包一旦被 Google 屏蔽（这种情况很常见），就会报错 Unexpected token 'l'。免费的公共代理列表也无济于事——我们测试了一个热门“高质量”列表中的 64 个代理，结果 0 个可用。本项目使用你自己的轮换代理，并支持自动重试，因此被屏蔽的请求会自动改用新的 IP 重试。

由 Denys Malieiev 开发。

---

为什么选择这个

修复的问题	详情
免费公共代理不可用	我们测试了 64 个，0 个能用。请自备轮换住宅代理（Webshare/IPRoyal/Smartproxy 免费套餐在 1 GB 流量下约可处理 4.6 万次请求）
遇到 Google 屏蔽时自动重试	Google 返回 HTML 时，我们会从代理池中换用一个新代理，最多重试 3 次。我们的端到端测试成功率：5/5
在封装层检测 HTML	其他 MCP 会让 JSON.parse 因难以理解的错误而崩溃。我们会在解析前检测 HTML
坦诚说明哪些功能不可用	我们有意不提供 get_trending_searches——如果没有住宅代理，Google 会频繁屏蔽 dailyTrends/realTimeTrends。我们不会隐瞒这一点
支持失败跟踪的代理池	失败 3 次的代理会自动移除。每次请求都会随机轮换
每次请求都轮换代理	每次请求都会从代理池中随机选择一个代理，Google 无法累积针对单个 IP 的速率限制

---

快速开始

npx @den.dance/google-trends-mcp

非标记 IP 开箱即用，但 Google 会严格限制数据中心网段的请求频率。要稳定使用，请配置代理（见下文）。

---

配置

1. 获取轮换代理账户

推荐选项（均提供免费套餐或按 GB 付费）：

• Webshare — 免费 1 GB 住宅代理流量（约 4.6 万次 Google Trends 请求）
• IPRoyal — 每 GB $1.75，价格最低
• Smartproxy / Decodo — 每 GB $4-7，代理池规模大
• Bright Data / Oxylabs — 每 GB $5-8，企业级服务

请确认服务提供商的 ToS 允许访问 *.google.com（大多数主要服务商都允许）。

2. 配置 Claude Desktop

编辑 Claude Desktop 配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

单个轮换端点（推荐——由服务提供商在内部轮换 IP）：

{
  "mcpServers": {
    "google-trends": {
      "command": "npx",
      "args": ["@den.dance/google-trends-mcp"],
      "env": {
        "PROXY_URL": "http://USER:[email protected]:7000"
      }
    }
  }
}

或者使用明确的代理列表（适用于 Webshare 这类按端口区分的代理）：

{
  "mcpServers": {
    "google-trends": {
      "command": "npx",
      "args": ["@den.dance/google-trends-mcp"],
      "env": {
        "PROXY_LIST": "http://user:pass@host1:6114,http://user:pass@host2:6014,http://user:pass@host3:5863"
      }
    }
  }
}

如果列表较长，可将代理写入文件（每行一个，允许使用 # 注释），然后指定该文件：

{
  "mcpServers": {
    "google-trends": {
      "command": "npx",
      "args": ["@den.dance/google-trends-mcp"],
      "env": {
        "PROXY_LIST_FILE": "/home/you/.config/google-trends/proxies.txt"
      }
    }
  }
}

# ~/.config/google-trends/proxies.txt
http://user:pass@host1:6114
http://user:pass@host2:6014
http://user:pass@host3:5863

请对该文件运行 chmod 600——凭据保存在其中。编辑后，可在 Claude 中运行 proxy_refresh 以热重载配置。

保存 JSON 配置后，重启 Claude Desktop。

3. 配置 Claude Code

claude mcp add google-trends \
  -e PROXY_URL="http://USER:[email protected]:7000" \
  -- npx @den.dance/google-trends-mcp

---

环境变量

变量	必需	描述
PROXY_URL	建议	单个轮换代理端点。由提供商在内部处理 IP 轮换。不进行验证，也没有回退方案
PROXY_LIST	替代项	以逗号分隔的代理列表（http://user:pass@host:port,...）。启动时验证，自动剔除无效项
PROXY_LIST_FILE	替代项	文件路径，每行一个代理（允许使用 # 注释和空行）。启动时验证；在 proxy_refresh 时重新读取
PROXIES_ENABLED	否	设置为 false 可停用所有代理逻辑（直接请求）。默认：启用

优先级：PROXY_URL > PROXY_LIST > PROXY_LIST_FILE。如果均未设置，请求将直接发送（不使用代理）——仅适用于未被标记的 IP。

---

工具

数据工具

• compare_keywords — 查询最多 5 个关键词随时间变化的搜索热度。返回相对得分时间线。
• get_related_queries — 获取某个关键词的热门及增长最快的相关查询。由 Google 的 relatedQueries 端点提供支持。
• get_interest_by_region — 获取某个关键词热度最高的 20 个地区。

管理工具

• proxy_status — 显示来源（single / env-list / env-file / none / disabled）、可用数量、使用时长、新鲜度和验证进度。
• proxy_refresh — 强制重新验证当前代理来源。在 PROXY_URL 模式下不执行任何操作。

有意不公开的工具

• get_trending_searches（每日／实时趋势）— Google 会严厉封锁这些端点。即使使用住宅代理，成功率也太低，无法发布。我们宁可不对此作虚假承诺。

---

已知限制

• Google 有时会比单个关键词更严格地封锁多关键词请求（2 个或 4 个关键词）。我们的自动重试机制会处理此情况，但如果 3 次尝试均遭封锁，请求就会失败。如果需要更高的容错能力，可在 trends-client.js 中增大 MAX_ATTEMPTS。
• 底层的 google-trends-api 库会抓取 Google 的内部端点，这些端点没有文档说明且可能发生变化。如果该库失效，此 MCP 也会随之失效。
• 对于非常高的使用量（>10k req/day），可考虑使用 SerpAPI 或 DataForSEO 等托管服务——在这种规模下，与自建代理相比，价格差异微乎其微，而且无需承担运维负担。

---

Claude 提示词示例

• “比较过去 12 个月里 ‘claude ai’、‘chatgpt’ 和 ‘gemini’ 的搜索热度”
• “大家在搜索哪些与 ‘sourdough bread’ 相关的内容？”
• “哪些地区对 ‘electric vehicle’ 的关注度最高？”
• “显示代理池状态”

---

架构说明

• server.js（MCP 处理程序）、proxy-manager.js（代理池／缓存）和 trends-client.js（含 DI 的重试逻辑）总计约 450 行
• 验证：并行工作线程（并发数 50）通过 trends.google.com/api/autocomplete/test 检查每个代理，并查找响应中的 anti-XSSI 前缀 )]}'
• 缓存：可用代理持久化到 proxies.json（已加入 gitignore），以输入列表的 SHA1 为键——来源发生变化时自动失效
• TTL：4 小时；缓存过期时在后台重新验证
• 失败跟踪：代理在每个会话中失败 3 次后，将从轮换列表中移除
• 重试：每次工具调用最多重试 3 次；遇到 HTML 响应或异常时，使用新的 getAgent()

---

开发

测试

# Unit only (fast, offline, no network)
npm test

# With coverage report (html in coverage/)
npm run test:coverage

# Integration (real Google hit, gated)
RUN_INTEGRATION=1 npm run test:integration

# E2E (spawns server.js, JSON-RPC over stdio)
RUN_E2E=1 npm run test:e2e

# Everything
npm run test:all

项目结构

• server.js — MCP 服务入口（stdio 传输）
• trends-client.js — Google Trends API 封装，遇到 HTML 时重试
• proxy-manager.js — 代理池、验证、缓存和来源优先级
• tests/unit/ — 纯单元测试，不访问网络（约 40 项测试，约 2 秒运行完毕）
• tests/integration/ — Google 实际端点测试（由 RUN_INTEGRATION=1 控制）
• tests/e2e/ — 通过 spawn 执行的完整 MCP 协议测试（由 RUN_E2E=1 控制）

---

安全

• 切勿将代理凭据提交到版本控制中。请使用 PROXY_LIST_FILE 指向仓库外权限为 chmod 600 的文件，或使用你的密钥管理器
• proxies.json 缓存（由已验证的代理构建）已加入 gitignore，且不会发布 — 安装后首次运行时会重新生成

---

许可证

MIT