Google Custom Search MCP

Google Custom Search MCP

英语 | 俄语

A1 Google Custom Search MCP 可让 AI 应用通过你的 Programmable Search Engine 使用自然语言搜索网页和图片。你可以查找网页，按语言、国家/地区、日期或网站缩小范围，翻阅搜索结果，并获取带缩略图的图片文件。

它使用 Google Custom Search JSON API 和你的 Google Cloud API 密钥。你可以决定搜索引擎涵盖的范围——几个网站或整个网络皆可；服务会明确说明 JSON API 的限制，而不会暗示它能完成所有搜索任务。

• 3 个工具。 网页搜索、图片搜索，以及一个原始 GET 备用入口，可用于传入类型化工具未公开的参数。
• 全程只读。 Custom Search JSON API 没有写入端点；所有工具都标记为只读，无法修改任何数据。
• 搜索范围由你掌控。 搜索引擎的配置决定搜索内容；结果和排名可能与 google.com 不同。
• 密钥保留在请求头中。 使用 API 密钥进行身份验证——无需 OAuth 或作用域；密钥通过 X-Goog-Api-Key 请求头传递，绝不会出现在 URL 中。
• 不是 Google Search Console。 它无法报告你自己的网站如何被编入索引或排名。

从一个只读问题开始：

查找上个月有关通行密钥普及情况的最新文章，并总结排名前三的结果。

连接服务 · 探索使用场景 · 查看技术文档

一分钟了解它的工作方式

你： 查找上个月有关通行密钥普及情况的最新文章，只看英语内容。

助手： 通过你的搜索引擎执行一次搜索，并显示每条结果的标题、链接和摘要。不会有任何更改——所有工具都为只读。

你： 显示下一页。

助手： 从 next_start 游标继续，并显示同一查询的第 11–20 条结果。

你： 现在查找同一主题的大幅新闻照片。

助手： 切换到图片搜索，返回图片文件及其尺寸、缩略图和图片所在页面。

目录

• 快速开始
• 你可以让它做什么
• 搜索如何运作
• 可能发生的变化
• 获取访问权限
• 配置
• 数据、限制与后台工作
• 技术文档
• 支持

快速开始

你需要 Node.js 20+、启用了 Custom Search API 的 Google Cloud API 密钥，以及 Programmable Search Engine ID（cx）。

1. 获取 API 密钥和引擎 ID。
2. 将服务添加到你的 AI 应用。
3. 提出上面的只读问题。

codex mcp add google-custom-search \
  --env GOOGLE_CUSTOM_SEARCH_API_KEY=your_api_key \
  --env GOOGLE_CUSTOM_SEARCH_ENGINE_ID=your_engine_id \
  -- npx -y mcp-google-custom-search@latest

codex mcp list

claude mcp add \
  --env GOOGLE_CUSTOM_SEARCH_API_KEY=your_api_key \
  --env GOOGLE_CUSTOM_SEARCH_ENGINE_ID=your_engine_id \
  --transport stdio --scope user google-custom-search \
  -- npx -y mcp-google-custom-search@latest

claude mcp list

{
  "mcpServers": {
    "google-custom-search": {
      "command": "npx",
      "args": ["-y", "mcp-google-custom-search@latest"],
      "env": {
        "GOOGLE_CUSTOM_SEARCH_API_KEY": "your_api_key",
        "GOOGLE_CUSTOM_SEARCH_ENGINE_ID": "your_engine_id"
      }
    }
  }
}

{
  "mcpServers": {
    "google-custom-search": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-custom-search@latest"],
      "env": {
        "GOOGLE_CUSTOM_SEARCH_API_KEY": "your_api_key",
        "GOOGLE_CUSTOM_SEARCH_ENGINE_ID": "your_engine_id"
      }
    }
  }
}

{
  "servers": {
    "google-custom-search": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-custom-search@latest"],
      "env": {
        "GOOGLE_CUSTOM_SEARCH_API_KEY": "${input:custom_search_api_key}",
        "GOOGLE_CUSTOM_SEARCH_ENGINE_ID": "${input:custom_search_engine_id}"
      }
    }
  },
  "inputs": [
    { "type": "promptString", "id": "custom_search_api_key", "description": "Google Cloud API key", "password": true },
    { "type": "promptString", "id": "custom_search_engine_id", "description": "Programmable Search Engine id (cx)" }
  ]
}

你可以让它做什么

搜索网络

• 查找某个主题的近期教程，并总结排名靠前的结果。
• 仅在 docs.python.org 内搜索，或排除你不信任的网站进行搜索。
• 显示同一查询的下一页结果。

缩小结果范围

• 仅搜索最近一个月发布的英文网页。
• 仅搜索 PDF 文件；要求包含准确短语或排除某个词语。
• 限定为某个国家/地区的内容，或限定为具有特定使用权限的资料。

查找图片

• 查找某个主题的大幅照片，并显示尺寸和缩略图。
• 仅查找剪贴画或线描图，或仅查找黑白图片。
• 显示每张图片所在的网页。

超越类型化工具的能力

• 使用类型化工具未公开的参数调用 API——使用 fields 精简响应、设置 lowRange/highRange、使用 hq。
• 获取包含推广内容和完整 pagemap 的原始响应封装。

搜索的工作方式

1. 每次查询都会通过一个 Programmable Search Engine，由其 cx ID 标识——可以是已配置的默认引擎，也可以是单次调用指定的 engine_id。引擎的配置决定搜索范围：特定网站列表，或启用“Search the entire web”后的整个网络。
2. 返回的结果经过规范化处理，包含标题、URL、摘要和元数据，并提供用于翻页的 next_start/previous_start 游标。total_results 是 Google 的估算值，翻页过程中可能会减少。
3. 每次调用最多返回 10 条结果，每次查询最多返回 100 条（start + num - 1 必须 ≤ 100）。服务器会在发出请求前拒绝超出范围的窗口——API 会在消耗一个配额单位后返回 400。
4. 引擎控制面板中必须启用 Image search，才能进行图片搜索；否则 API 会返回 400。

响应中的 corrected_query 仅提供拼写建议——结果仍对应原始查询。这是 Programmable Search，而不是 Google Search Console：此 API 无法报告你自己的网站如何被编入索引或排名。

可能发生的变化

所有工具（包括应急通道）都带有只读标注。Custom Search JSON API 只有一个 GET 端点，不支持写入，因此调用唯一消耗的是你的每日配额单位。

获取访问权限

Google Custom Search 使用 API 密钥进行身份验证；不涉及 OAuth 或权限范围。

1. 创建或选择一个 Google Cloud 项目，并启用 Custom Search API。
2. 在 APIs & Services → Credentials 下创建 API key。将密钥限制为仅用于 Custom Search API 是个好习惯。
3. 在控制面板中创建 Programmable Search Engine，并复制其 Search engine ID（cx）。启用 Search the entire web 以搜索开放网络，启用 Image search 以使用图片工具。

请将 API 密钥视为密码。服务器会在 X-Goog-Api-Key 标头中发送密钥，绝不会将其放入 URL，因此记录或回显的 URL 不会泄露密钥。

配置

即使没有凭据，服务器仍会启动并完成 MCP 握手；首次调用工具时会明确说明需要设置哪些变量。唯一无效的配置是只设置引擎 ID、未设置 API 密钥——密钥无法按次调用提供，因此两者必须同时设置。

数据、限额与后台工作

• 请求会发送到 Google。 本地服务会调用 Custom Search JSON API。匿名遥测包含安装 ID、软件包版本、AI 客户端和平台版本以及工具名称，但绝不会包含 API 密钥、搜索查询、结果或工具参数。设置 ASKADS_TELEMETRY=0 即可选择退出。
• Google 设有每日配额。 三种工具中的任何一种每次调用都会消耗项目配额中的 1 个单位——免费额度为每天 100 次查询，启用结算后最高为每天 10,000 次。遇到 429 时，服务会遵循 Retry-After 进行退避；由于整个 API 都是幂等 GET 请求，5xx 和网络错误也会重试，而 400/403 则会立即失败。
• 没有后台轮询。 服务仅在被调用时运行。如果你的 AI 应用支持计划任务，可以定期重新运行搜索——每次运行仍会消耗配额单位。

技术文档

• MCP 能力目录 — 面向任务的页面，涵盖每种工具。
• 所有工具和输入
• 开发文档
• 发布文档
• Custom Search JSON API 参考

支持

发现 Bug 或有使用场景需求？创建 Issue或在 Telegram 上留言。

你已经读到最后啦！