Google Trends MCP Server

一个托管的 Model Context Protocol (MCP) 服务器，让 Claude、Cursor、Windsurf 以及任何其他 MCP 客户端都能使用一个 Google Trends 工具。你可以按时间、按地区拉取兴趣趋势，也可以拉取任意搜索词的上升/热门相关查询与话题，全部以结构化 JSON 返回；无需维护抓取库，也不需要 Google 账号。

https://mcp.hasdata.com/api/mcp?apis=google_trends

目录

• 你需要什么

• 快速开始

• 示例提示词

• 工具

• 错误与失败路径

• 定价、免费额度与限制

• 工具选择

• 与同类方案对比

• 常见问题

• HasData 相关链接

• 开发

• 参与贡献

• 许可证

你需要什么

一个 MCP 客户端，以及一个来自控制台的 HasData API 密钥。注册免费，无需信用卡；按每次 5 积分的费率，试用额度覆盖约 200 次调用。这是一个远程服务器，因此最简便的方式是给客户端一个 URL 和一个 x-api-key 头，不需要运行容器，整个流程里也不会接触 Google 账号。如果客户端只支持 stdio，可以通过一个轻量启动器接入远程服务器，该启动器发布在 npm 上，名为 @hasdata/google-trends-mcp，同时发布在 PyPI 上，名为 hasdata-google-trends-mcp，见下文。

快速开始

服务器的 URL 对所有客户端都一样。我们在 Claude Code 和 Claude Desktop 中实际操作过它。其余小节均按各客户端文档中定义远程服务器的格式给出。

支持 OAuth 的客户端可以把同一个 URL 添加为连接器并直接登录，无需在配置文件中再放密钥。

claude mcp add --transport http google-trends "https://mcp.hasdata.com/api/mcp?apis=google_trends" \
  --header "x-api-key: HASDATA_API_KEY"

依次打开 Settings → Connectors → Add custom connector，粘贴 https://mcp.hasdata.com/api/mcp?apis=google_trends 并登录。

如果走配置文件方式：Claude Desktop 只加载本地（stdio）服务器，所以需要通过 stdio 启动器访问远程服务器。@hasdata/google-trends-mcp 这个包就是这个启动器，它会从环境变量读取密钥。把它加到 claude_desktop_config.json：

{
  "mcpServers": {
    "google-trends": {
      "command": "npx",
      "args": ["-y", "@hasdata/google-trends-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}

如果使用 Python 而不是 Node，把启动器换成 PyPI 包，uvx 无需手动安装即可运行它：

{
  "mcpServers": {
    "google-trends": {
      "command": "uvx",
      "args": ["hasdata-google-trends-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}

~/.cursor/mcp.json 用于每个项目的配置，.cursor/mcp.json 用于某个项目的配置：

{
  "mcpServers": {
    "google-trends": {
      "url": "https://mcp.hasdata.com/api/mcp?apis=google_trends",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

配置文件是 ~/.codeium/windsurf/mcp_config.json。Windsurf 把字段叫 serverUrl，而不是 url：

{
  "mcpServers": {
    "google-trends": {
      "serverUrl": "https://mcp.hasdata.com/api/mcp?apis=google_trends",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

把 .vscode/mcp.json 放在工作区里：

{
  "servers": {
    "google-trends": {
      "type": "http",
      "url": "https://mcp.hasdata.com/api/mcp?apis=google_trends",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

示例提示词

提示词，不是代码。把下面任意一条粘进去，Agent 会自己选用工具。每条都标明了需要的调用次数，因为每次成功调用都会消耗 5 积分。

绘制"cold brew coffee"在美国过去 12 个月内的兴趣，并告诉我它在哪个几周达到峰值。

一次调用，5 积分。周级序列在单个请求中就能全部返回。

针对美国地区，帮我列出 "cold brew coffee" 的上升相关查询，并标记出 Breakout 的项。

一次调用，5 积分。

比较 "cold brew" 和 "iced coffee" 两个词的世界范围五年兴趣，说明哪个在上升。

一次调用，5 积分。工具会在一个 timeseries 请求里接受多个对比词。

展示过去 90 天内各州对 "sunscreen" 的兴趣，以便看到需求最高的地方。

一次调用，5 积分。这是按州粒度的分地区兴趣视图。

多个词的横向比较放在同一次 timeseries 调用里。地区拆分、相关查询、相关主题分别是各自的 dataType，因此"想要图表及其上升查询"这种需求需要两次调用。

工具

只有一个工具，只读。下面的示例来自真实调用且做了节选，数字会随趋势移动而变化，把它当作格式示例来读。工具名链接到端点参考文档，那里有完整参数列表。

这个示例是 payload，不是完整响应。一次 tools/call 结果会携带一个文本块，而该文本本身就是一个 JSON，包含 url、status、text、json，抓取到的数据放在 json 键下。从原始 JSON-RPC 响应出发，路径是 result.content[0].text，解析后再取 .json 字段。聊天客户端会自动帮你解开这层，直接调接口的代码则不会。

获取 Google Trends 数据

hasdata_google_trends_getTrendsData

获取兴趣随时间趋势、兴趣分地区，或某个搜索词的相关查询与相关兴趣。

响应里的哪个键取决于 dataType。timeseries 返回 interestOverTime.timelineData，geoMap 返回分地区兴趣，related 类型返回 relatedQueries 或 relatedTopics，每种又分为 rising 和 top。请读取你请求类型对应的键。

timeseries（默认）每个点返回 0~100 的数值，以字符串形式返回，并同时预解析在 extractedValue 里。最近的数据点通常带 isPartial: true，表示当周还在累计中。在计算趋势前把它去掉，否则最后一个柱状图会显示一次并不真实的回落。

{
  "interestOverTime": {
    "timelineData": [
      { "date": "Apr 12 – 18, 2026", "timestamp": "1775952000", "isPartial": false,
        "values": [{ "query": "cold brew coffee", "value": "100", "extractedValue": 100, "hasData": true }] },
      { "date": "Aug 23 – 29, 2026", "timestamp": "1787443200", "isPartial": true,
        "values": [{ "query": "cold brew coffee", "value": "44", "extractedValue": 44, "hasData": true }] }
    ]
  }
}

relatedQueries 分为 rising 和 top。rising 条目以类似 +300% 的百分比出现，无法评分的直接为 Breakout，而 extractedValue 给出它背后的数值。Breakout 对应的 extractedValue 是一个远高于任何真实百分比的哨兵值，所以排序请按字符串标签，而不是原始数字。

{
  "relatedQueries": {
    "rising": [
      { "query": "organic cold brew coffee", "value": "+300%", "extractedValue": 300, "link": "https://trends.google.com/trends/explore?q=organic+cold+brew+coffee&date=today+12-m&geo=US" }
    ],
    "top": [
      { "query": "how to cold brew coffee", "value": "100", "extractedValue": 100, "link": "https://trends.google.com/trends/explore?q=how+to+cold+brew+coffee&date=today+12-m&geo=US" }
    ]
  }
}

端点参考 列出了该工具支持的全部 geo、cat 和日期格式。

错误与失败路径

你的客户端几乎不会从工具调用里看到 HTTP 错误码。MCP 层会返回 200，把失败放进结果里，并设 isError: true、原因是文本。Agent 平常期待状态行的场景，现在读到的是一条文本。

错误的密钥会表现为工具输出，而不是连接失败。 tools/list 接受任何非空密钥并返回工具，所以客户端完成握手并显示绿色。第一次工具调用随后返回 isError: true 和文本 HasData API error: 401 Unauthorized。要留意这个字符串，因为在此之前流程不会报告任何问题。

缺少密钥是唯一的“真” HTTP 错误。 鉴权先于任何工具运行，连接本身会以 401 失败。CORS 一同生效，浏览器客户端能读到具体状态，而不是不透明的网络错误。

导致工具 Schema 校验失败的参数会在抓取之前就被拒绝。 服务器返回 isError: true 和文本 MCP error -32602: Input validation error，并标明错误的字段。不会产生任何抓取，也不消耗配额。

搜索量太小的词会返回成功结果，但数据数组为空，而不是报错。 冷门词在 Google Trends 里没有展示内容，且 requestMetadata.status 仍然 ok。在画图先检查 data 点。

不支持的标识符会返回 400，并把 requestMetadata.status 置为 error。常见的触发原因是 geo 或 cat 传了未知的值。

结果里如果带数据，也会带 requestMetadata.id，支持时记得把它贴出来。

定价、免费额度与限制

每次 Google Trends 调用按成功调用计 5 积分。返回体量不改变价格。单周的序列和一年周序列都是同一价格。

免费试用是 30 天后 1000 积分，无需卡，300 次 Google Trends 调用量。之后只要活跃账户余额低于 100 积分，每天都会在补充 100，因此低用量 agent 可以在免费队列长时间跑下去。

付费从每月 $49 起，约 200 000 积分，也就是 4 万次调用。单价随用量递增，从入门方案的 每 1,000 次 $1.23 到 Business 的 $0.50、Growth 的 $0.42，跟最大规模的高用量方案的 $0.37。

你的方案还决定并发。免费试用只能同时 1 个请求，Startup 15 个，Business 30 个，Growth 50 个，高用量方案从 200 到 1500 并发。无人值守的场景请一律防御性处理超出并发的场景。

返回非 200 的请求不计费。一次成功但没找到数据的调用，照样算一次调用。

工具选择

apis 查询参数决定 Agent 会看到哪些工具。工具越少，工具定义占的上下文越少，模型拿错工具的概率也越低。

?apis=google_trends              the one tool in this repo
?apis=google_trends,google_serp  add Google search
?apis=google_trends,youtube      trends plus YouTube

该参数接受 google_trends 之类的提供方名称以及各个 API 名称。拼错的名称会被忽略。如果所有名称都是错的，请求就会以 400 失败，并返回一个同时列出未识别内容和所有有效值的响应体。省略该参数后，同一端点会暴露全部 57 个 HasData 工具。

对比

Google 并没有发布公开的 Trends API。两种常见的做法是：非官方的 pytrends 库（它反向解析相同的内部端点，一旦 Google 修改这些端点或限制调用方就会被破坏），以及自己写爬虫。本服务器在稳定的 schema 背后完成这部分工作。

如果你已经在低流量下运行 pytrends，并且不介意在它崩溃时去修复，那它仍然是一个免费的方案。本服务器则专门面向那些希望每次都以相同数据结构返回数据的 agent 和 pipeline。

FAQ

有官方 Google Trends API 吗？

没有。Google 从未发布过公开的 Trends API。所有方案读取的都是 trends.google.com 网站所使用的相同内部端点。本服务器由 HasData 维护，并以结构化 JSON 的形式返回结果。

什么是 Google Trends MCP 服务器？

它是一台将 Google Trends 作为可由 AI 客户端调用的工具来暴露的服务器。客户端通过 Model Context Protocol 发起工具调用，服务器负责取回数据并返回结构化 JSON，模型再使用该结果。本服务器只暴露一个工具，并且是远程运行的，因此客户端只需连接一个 URL，不需要启动任何本地进程。

这些数字表示绝对搜索量吗？

不是，Google Trends 本身也不是。这些值的范围会按你所请求的查询、时间窗口和区域缩放为 0 到 100。它们是相对的关注度，只能用来观察趋势和比较，不能作为搜索次数使用。

为什么最后一个数据点比其他数据点低？

最近的一个时间桶通常还在填数中，所以返回时带 isPartial: true。请在计算趋势前把它丢弃。

能不能一次比较多个词？

可以。在 timeseries 和 geoMap 中使用 q，把多个词用逗号分隔。 related-query 和 related-topic 类型则只接受单个词。

能不能把它和其他 HasData API 一起使用？

可以。apis 参数接收的是一个列表，?apis=google_trends,google_serp 会给你的 agent 同时提供 Trends 和 Google 搜索结果。（省略该参数 就能获取全部工具。）

合规性与个人数据

HasData 只访问公开可用的数据。平台的条款可能对自动访问作出限制，自行合规是你的责任。

HasData 链接

开发

这个仓库是远程服务器的配置和文档。没有构建步骤，也没有需要容器化的内容。

test/ 中的测试会验证工具契约，这部分是即没有此仓库提交也可能被破坏的。它们检查 ?apis=google_trends 是否确实只返回一个工具，是否仍声明其必需参数，名称是否保持不变，以及当前用的密钥是否真的被接受。最后一项检查会真实调用一次工具并消耗 5 积分，这，是一只会因为正常原因而失败的金丝雀的价格。

# macOS and Linux
HASDATA_API_KEY=your_key_here npm test

# Windows PowerShell
$env:HASDATA_API_KEY="your_key_here"; npm test

同一套测试在每次 push 到 CI 中运行一次，并每周运行一次，因为上游的工具列表可能在没有此仓库改动的情况下发生变化。失败意味着工具列表移动了、密钥失效了，或者端点不可达，断言消息会指出具体是哪种情况。

贡献

对参数表和响应示例的修正最受关注的价值，因为那是容易偏离的部分。请随修正一起附带所执行的调用和实际返回的响应。从 fork 发起的 pull request 会在没有密钥的情况下运行测试套件，而真实工具调用检查会跳过而不是直接变成红色失败。

许可证

MIT.请参阅 LICENSE。