Google Search MCP Server

Google Search MCP 服务（SERP）

一个托管的模型上下文协议（MCP）服务，为 Claude、Cursor、Windsurf 和任何其他 MCP 客户端提供 8 种只读 Google Search 工具。获取实时 SERP 及其 AI Overview 和 People Also Ask，运行 Google AI Mode 查询，并以结构化 JSON 读取新闻、购物、产品详情和短视频结果，无需 Google Cloud 项目，也无需设置搜索引擎。

每月赠送 1,000 个免费点数，无需信用卡，可用于 100 次完整 SERP 调用，或 200 次 5 点数调用。

https://mcp.hasdata.com/mcp?apis=google_serp

• 提示词和资源

这里的“SERP”和“Google Search”指的是同一项产品。此服务会解析并返回 Google 搜索引擎结果页面。

目录

• 所需条件
• 快速开始
• 示例提示词
• 工具
• 错误和失败情况
• 定价、免费套餐和限制
• 工具选择
• 对比
• 常见问题
• HasData 链接
• 开发
• 贡献
• 许可证

所需条件

支持带自定义标头的可流式 HTTP 的 MCP 客户端。一个 HasData API 密钥，可在控制面板中获取，免费创建，无需信用卡；免费套餐每月大约可调用 100 到 200 次，具体取决于所用工具。无需其他条件。这是一个远程服务，因此最简单的接入方式是使用 URL 和标头，无需设置 Google Cloud 项目或 Programmable Search Engine。仅支持 stdio 的客户端可改用 @hasdata/google-search-mcp（npm）或 hasdata-google-search-mcp（PyPI）启动器。

快速开始

所有客户端使用相同的服务 URL。我们已在 Claude Code 和 Claude Desktop 中亲自运行。其他代码块则遵循各客户端针对远程服务的文档格式。

支持 OAuth 的客户端可以将相同的 URL 添加为连接器，并直接登录，无需在配置文件中填写密钥。

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

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

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

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

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

{
  "mcpServers": {
    "google-search": {
      "url": "https://mcp.hasdata.com/mcp?apis=google_serp",
      "type": "streamableHttp",
      "headers": { "x-api-key": "HASDATA_API_KEY" },
      "disabled": false
    }
  }
}

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

{
  "mcpServers": {
    "google-search": {
      "httpUrl": "https://mcp.hasdata.com/mcp?apis=google_serp",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}

提示词示例

在 Google 上搜索 best running shoes，并提供自然搜索结果前十名以及 AI Overview。

调用一次，消耗 10 个积分。SERP 响应会在自然搜索结果旁内嵌返回 AI Overview。

对于同一个查询，提取每个“用户也会问”的问题，并获取其 AI Overview 答案及来源。

每个问题调用一次，每次消耗 10 个积分。每个 relatedQuestions 条目都包含一个 aiOverview.pageToken，AI Overview 工具会将该令牌转换为答案内容块及其参考资料。

询问 Google AI Mode：what is the Model Context Protocol，并提供答案及其引文。

调用一次，消耗 10 个积分。AI Mode 会以文本内容块的形式返回生成的答案，并附上参考资料列表。

在 Google Shopping 上搜索 nike air max，然后获取排名第一的结果的完整商品卡片：所有销售该商品的商店、价格范围以及评价明细。

调用两次。Shopping 消耗 10 个积分，并为每件商品返回一个令牌；沉浸式商品工具消耗 5 个积分，可将该令牌展开为商店、款式和评价信息。

获取 artificial intelligence 的最新 Google News，并另外获取 cooking pasta 的短视频搜索结果。

调用两次，每次消耗 10 个积分。

整个工作流主要依赖两条链路。SERP 响应会内嵌返回 aiOverview，并为每个“用户也会问”的问题提供一个 pageToken，因此提取 Google 的生成式答案，要么随搜索免费完成，要么针对每个问题额外调用一次，消耗 10 个积分。Shopping 搜索结果也会为每件商品返回一个令牌，因此从商品列表跳转到完整的多商店商品卡片只需调用一次。

工具

这 10 个工具均为只读。下面的示例经过了删减，取自实际调用；其中的结果会随 Google 的变化而变化，因此请将它们视为数据结构示例。每个工具名称都链接到其端点参考文档。

这些示例展示的是载荷，而非完整响应。tools/call 的结果包含一个文本块，该文本本身是包含 url、status、text 和 json 的 JSON，抓取的数据位于 json 下。从原始 JSON-RPC 响应中，路径为 result.content[0].text，解析后再取 .json。聊天客户端会替你解包，直接与端点交互的代码则不会。

Google SERP

hasdata_google_serp_serp_getSearchResults

查询的完整结果页。

返回 searchInformation、organicResults、aiOverview、relatedQuestions、relatedSearches、perspectives、immersiveProducts 和 pagination，具体取决于 Google 针对该查询显示的内容。自然搜索结果条目包含 position、title、link、displayedLink、source、snippet、snippetHighlitedWords、date 和 images。

AI Overview 有两种返回方式。通常，aiOverview 会以内嵌形式返回，其中包含可直接读取的 textBlocks 和 references。有时 Google 会要求提供令牌，此时 aiOverview 会返回 pageToken 和 hasdataLink，而不是内容块。每个 relatedQuestions 条目也属于第二种情况。它包含一个 question 和一个带有相同 pageToken 和 hasdataLink 的 aiOverview，可通过下方的 AI Overview 工具展开。因此，People Also Ask 的回答也是 AI Overview，需要逐个令牌获取。顶层的 aiOverview 在大多数查询中以内嵌形式返回，少数情况下则返回令牌，因此请兼顾这两种情况进行读取。

{
  "organicResults": [
    {
      "position": 1,
      "title": "The 15 Best Running Shoes of 2026",
      "link": "https://www.runnersworld.com/gear/a19663621/best-running-shoes/",
      "source": "Runner's World",
      "snippet": "The Brooks Ghost is our No. 1 shoe when we recommend new trainers…"
    }
  ],
  "aiOverview": {
    "textBlocks": [ { "type": "paragraph", "snippet": "The best running shoes depend on your goal…" } ],
    "references": [ { "index": 0, "title": "7 Best Running Shoes in 2026 - RunRepeat", "link": "https://runrepeat.com/guides/best-running-shoes" } ]
  },
  "relatedQuestions": [
    { "question": "What are the top 5 best running shoes?", "aiOverview": { "pageToken": "eyJpZCI6…", "hasdataLink": "https://api.hasdata.com/scrape/google/ai-overview?pageToken=eyJpZCI6…" } }
  ],
  "pagination": { "next": "…" }
}

Google AI Overview

hasdata_google_serp_ai_overview_getAiOverviewResponse

将 AI Overview 令牌展开为回答。

返回包含 textBlocks 和 references 的 aiOverview。当 SERP 返回的是令牌而不是内容块时，可通过此工具读取 AI Overview；也可将每个 People Also Ask 问题转换为带引用的回答。

令牌的有效期约为 4 分钟。令牌过期后不会返回空结果，而是会作为工具错误失败，返回 isError: true 和文本 HasData API error: 400 Bad Request。请像处理错误密钥一样捕获此错误，并重新运行 SERP 以获取新令牌。

{
  "aiOverview": {
    "textBlocks": [ { "type": "paragraph", "snippet": "The top five running shoes feature versatile options for daily training and racing…" } ],
    "references": [ { "index": 0, "title": "…", "link": "https://…" } ]
  }
}

Google AI Mode

hasdata_google_serp_ai_mode_getAiModeResponse

Google 针对查询生成的 AI Mode 回答，即对话式搜索结果。

返回 textBlocks 和 references，即生成的回答及其引用的来源。

Google SERP Light

hasdata_google_serp_serp_light_getSearchResults

一种成本更低的搜索，可返回页面的核心内容。

返回 organicResults、aiOverview、relatedSearches、filters、appliedLocation、searchInformation 和 pagination。它的积分消耗是完整 SERP 的一半，适用于只需要自然搜索结果和 AI Overview，而不需要额外模块的场景。

Google News

hasdata_google_serp_news_getGoogleNews

查询或新闻版块的 Google News 结果。

返回 newsResults、menuLinks、relatedTopics 和 relatedPublications。每条新闻都包含 position、title、link、source（含 name 和 icon）、thumbnail 和 date。

Google Shopping

hasdata_google_serp_shopping_getSearchResults

查询的购物结果。

返回 shoppingResults、filters、refineSearchFilters、searchInformation 和 pagination。每条结果都包含 position、title、productId、price、extractedPrice、rating、reviews、source、category、thumbnail 和 immersiveProductPageToken。

immersiveProductPageToken 是下方沉浸式商品工具的输入。这是临时令牌，因此如果需要获取商品数据，请在令牌有效时展开；如果旧令牌失效，请重新执行购物查询以获取新令牌。

{
  "shoppingResults": [
    {
      "position": 1,
      "title": "Men's Nike Alphafly 3",
      "productId": "13366226642799457284",
      "price": "$285.00",
      "extractedPrice": 285,
      "rating": 4.5,
      "reviews": 120,
      "source": "Nike",
      "immersiveProductPageToken": "eyJyZHMiOiJQQ18…"
    }
  ]
}

沉浸式商品

hasdata_google_serp_immersive_product_getImmersive_e29f691177

购物结果背后的完整商品卡片。

返回一个 productResults 对象，包含 title、brand、rating、reviews、priceRange、一个列出所有卖家及其价格和链接的 stores 数组，以及 variants、reviewsImages、userReviews、topInsights、aboutTheProduct 和 discussionsAndForums。这项调用可以将单个商品列表扩展为跨商店的完整概览。

{
  "productResults": {
    "title": "Men's Nike Alphafly 3",
    "brand": "Nike",
    "rating": 4.4,
    "reviews": 1077,
    "priceRange": "$221-$295",
    "stores": [ { "name": "eBay", "link": "https://www.ebay.com/itm/…", "price": "$221" } ],
    "storesNextPageToken": "Mw=="
  }
}

将 storesNextPageToken 作为 nextPageToken 参数传回，即可翻阅商店列表。

Google 短视频

hasdata_google_serp_short_videos_getShortVideosSearchResults

Google 针对某个查询显示的短视频结果。

返回 shortVideos，其中每项包含 position、title、link、source、sourceLogo、profileName、duration、clip 和 thumbnail。

提示词和资源

该服务提供 5 个提示词，即现成的工作流，客户端可以直接提供给用户，而不必让用户自行编写工具调用。

此外，该服务还公开了 10 个资源，每个资源对应一个可接受值为固定列表的参数。读取资源比从被拒绝的调用中学习相关词汇更省事，而且不会消耗积分。每个 URI 的格式为 hasdata://google_serp/<parameter>。

这两个列表均无需 API 密钥即可获取，因此客户端可以在用户注册之前读取它们。

错误和失败路径

客户端几乎不会从工具调用中收到 HTTP 错误代码。MCP 层会返回 200，并将失败信息放在结果中，其中 isError 设为 true，原因以文本形式给出。Agent 读到的是一条消息，而不是你可能预期的状态行。

错误的密钥会显示为工具输出，而不是连接失败。 列出工具时接受任何非空密钥，客户端会完成握手并显示绿色状态。随后首次调用工具时，会返回 isError: true，文本为 HasData API error: 401 Unauthorized。请留意这段字符串，因为流程中更早的步骤不会报告此问题。

唯一真正的 HTTP 错误是缺少密钥。授权会在调用任何工具前执行，连接本身会以 401 失败。

不符合架构的参数会在发起搜索前被拒绝。 未提供 q 的搜索会返回 isError: true，文本为 MCP error -32602: Input validation error，并指出出错字段。不会获取任何内容，也不会产生费用。

过期的 AI Overview 令牌会以错误形式失败。 SERP 响应令牌的有效期约为 4 分钟。展开之前保存的令牌会返回 isError: true，文本为 HasData API error: 400 Bad Request，与错误密钥的错误形式相同。请捕获此错误并重新运行 SERP，以获取新令牌。

Google 未显示的区块不会出现，而不是为空。 如果查询没有 AI Overview、购物面板或 People Also Ask，响应中就不会包含这些键，而不是将其设为空。读取前请先检查键是否存在。

包含数据的结果还会提供 requestMetadata.id，可在联系支持时引用；此外还包含指向该次调用所存储产物的 html 和 json 链接。

定价、免费层级和限制

每种工具单独计费。完整 SERP、AI Mode、News、Shopping、短视频、沉浸式产品和 AI Overview 工具每次调用消耗 10 个积分。SERP Light 消耗 5 个积分。SERP 响应中内嵌的 AI Overview 免费，包含在这次 10 积分的调用中；但使用 AI Overview 工具展开令牌（包括每个 People Also Ask 令牌）需另行调用一次，消耗 10 个积分。响应大小不会影响价格。

免费层级每月提供1,000 个积分，无需信用卡，可用于 100 次完整 SERP 调用或 200 次 5 积分调用。积分会随计费周期续期，因此低调用量的 Agent 可以无限期使用免费层级。

付费计划起价为每月 $59，包含 200,000 个积分。用量越大，每个积分的价格越低；当前价格请查看定价页面。

计划还决定并发数。免费层级允许同时处理 1 个请求，Startup 为 5 个，Basic 为 15 个，Growth 各层级则为 50 到 500 个。并发数是唯一的限流机制，没有单独的每分钟请求数上限。对于任何无人值守的任务，都应谨慎处理超出并发限制的情况，因为跨多个查询并行发起请求的 Agent 会先触及上限。

工具选择

?apis=google_serp 会公开这八种工具。该参数接受一个列表，?apis=google_serp,google_maps 则会在搜索工具之外加入 Google Maps 工具。不使用该参数时，会公开 HasData 提供的所有工具，目前共 57 种。

通常，较短的列表是更好的默认选择。模型从八种工具中选择时，比从五十七种工具中更容易选对；而且每轮对话中，工具描述本身也会占用上下文。

对比

Google 已不再提供通用搜索 API。官方方案是 Custom Search JSON API，但它要回答的问题与这里不同。

Custom Search JSON API 会搜索你配置的 Programmable Search Engine，范围可以是你列出的网站，也可以是启用全网索引后的整个网络。它每天提供 100 次免费查询，之后按千次收费，并设有每日上限，而且返回的结果集经过了精简。它不会返回 AI Overview、People Also Ask、本地商家列表、购物、新闻或短视频，因为这些是实时结果页的功能，而不是 API 的功能。如果你想搜索自己的网站或一组固定网站，并遵守 Google 的官方条款，那么它就是合适的工具。

此服务会解析访客所见的实时 Google 结果页。无需进行任何配置，查询会在整个 Google 搜索范围内执行，而不是针对经过筛选的搜索引擎；AI Overview、People Also Ask、购物及其他内容也会以结构化区块的形式返回。

有两点可以决定如何选择。如果你只需要搜索自己的网站，并且希望使用 Google 的官方 API，那么 Custom Search JSON API 就合适。如果你需要真实的 SERP、其中的 AI Overview，或 Google 向搜索用户展示的任何面板，那么官方 API 不会返回这些内容，而此服务可以。

此服务不提供的功能。 不会抓取结果背后的网页，不提供排名历史，也不会执行任何写入操作。它只返回解析后的结果页。

常见问题

什么是 Google Search MCP 服务？

它是一种将 Google 搜索结果作为工具提供给 AI 客户端调用的服务。客户端通过 Model Context Protocol 发送工具调用，服务获取结果页并返回结构化 JSON，大模型会处理结果，而不会看到 HTML 页面。此服务提供八个只读工具，并以远程方式运行，因此客户端只需连接到一个 URL，无需启动本地进程。

这里的 SERP 和 Google Search 是一回事吗？

是。SERP 是搜索引擎结果页。这些工具返回 Google 的结果页，因此在此代码库中，“SERP API”和“Google Search API”指的是同一回事。

是否有 Google 官方的 Google Search MCP 服务？

Google 没有发布 MCP 服务，也没有通用搜索 API。最接近的官方产品是 Custom Search JSON API，它会搜索你配置的 Programmable Search Engine。包括此服务在内的多个社区 MCP 服务，则会返回实时结果页。

如何获取 AI Overview？

运行一次 SERP 调用。aiOverview 通常会与 textBlocks 和 references 一起内联返回。如果它以 pageToken 的形式返回，或者遇到 People Also Ask 中的问题，请将该令牌传给 AI Overview 工具以获取答案。令牌很快就会过期，因此请使用新调用获取的令牌展开内容。

我需要 Google Cloud 项目或 Programmable Search Engine 吗？

不需要。唯一需要的凭据是你的 HasData 密钥。无需在 Google Cloud 中创建任何内容，也无需管理 API 专属配额。

API 密钥会过期吗？

不会。密钥不会过期。需要时可在控制面板中轮换密钥。

数据是实时的还是缓存的？

是实时数据。每次调用都会在请求时获取结果页，并拥有各自的 requestMetadata.id。两次相同的调用是两次独立获取，不会重放已存储的副本。

这与 Google 有关联吗？

没有。HasData 是一项独立服务，与 Google 没有关联，也未获得 Google 的认可或赞助。Google 是其各自所有者的商标。这些工具仅处理公开数据，您有责任确保使用结果时遵守 Google 的条款以及适用于您的法律。

HasData 链接

开发

此仓库包含远程服务的配置和文档。无需构建，也没有需要容器化的内容。

仓库还包含一项契约测试。README 记录了 8 个具有特定参数的工具，而上游工具列表可能会在此处没有提交记录的情况下发生变化，导致此文件悄悄向您提供错误信息。该测试会断言文档中所述的工具及其参数确实存在，并且每周在 CI 中运行，也会在每次推送时运行。

HASDATA_API_KEY=your_key_here npm test

在 PowerShell 中：

$env:HASDATA_API_KEY = "your_key_here"; npm test

最后一项检查会执行一次真实搜索，费用为 10 个积分；这是一个可能因合理原因失败的金丝雀测试，值得这笔开销。只要密钥非空，列出工具就会成功，因此只列出工具的测试即使使用了已撤销的密钥也会通过。

贡献

修正工具表格和响应示例是最有价值的贡献，因为这些内容最容易过时。请附上您发出的调用和收到的响应。来自分支仓库的拉取请求会在不使用密钥的情况下运行测试套件，实时检查则会跳过，而不会报错。

许可证

MIT。请参阅 LICENSE。