Google Search Console MCP

一个用于 Google Search Console API 的 MCP 服务器——提供搜索表现数据、URL 索引状态、站点地图管理和资源列表功能。

同一套代码库支持三种运行方式：stdio（本地，通过 npx）、Streamable HTTP（自托管）和 Cloudflare Workers（托管在 URL 上）。实现了 MCP 2026-07-28，并自动回退到 2025-11-25、2025-06-18 和 2025-03-26，因此无论客户端处于协议变更的哪一侧都能正常工作。

零运行时依赖。

快速开始

npx google-search-console-mcp auth

它会引导你创建 Google OAuth 客户端、运行授权流程、对照真实 API 验证凭据，并打印一段可直接粘贴到 MCP 客户端中的配置块。三分钟搞定，大部分时间花在等待 Google Cloud 的界面上。

然后把打印出的 JSON 粘贴到你的客户端配置中并重启即可。

Related MCP server: searchconsole-mcp

工具

覆盖 Search Console API v1 中的每个方法，外加两个复合工具。

站点验证以及 sites.add/sites.delete 有意不开放——添加和验证资源属于浏览器操作流程，不适合放在代理工具中。

服务器还提供提示词（performance_review、indexing_audit、query_opportunities、sitemap_health）和资源（gsc://guide/search-analytics、gsc://guide/url-inspection、gsc://guide/sitemaps），代理可按需读取。

身份验证

第 1 步——创建 Google OAuth 客户端

这一步只需做一次。服务器无法替你完成：Google 要求必须有人在控制台里操作。

1. 打开 Google Cloud Console，选择或创建一个项目。

2. 为该项目启用 Search Console API。

3. 配置 OAuth consent screen。个人使用选择 External 即可。在 Test users 下添加你自己的 Google 账号。

4. 进入 Credentials → Create credentials → OAuth client ID。应用类型选择 Desktop app。

5. 复制 Client ID 和 Client secret。

Testing 与 Published 的区别。 当同意屏幕处于 Testing 状态时，Google 会在 7 天后使刷新令牌过期，你需要每周重新运行 auth。发布应用（同意屏幕 → Publish app）可让令牌长期有效。对于单用户内部工具，发布是安全的，只要保持在 webmasters 范围内，就不需要 Google 的验证审核。

第 2 步——运行设置流程

npx google-search-console-mcp auth

这会打开一个由 127.0.0.1 提供的小型设置页面。粘贴客户端 ID 和密钥，选择完全访问或只读访问，它会运行授权流程，将授权码（通过 PKCE）兑换为刷新令牌，并调用 list_sites 来验证凭据可用——向你展示它们能访问到的确切资源。

最终页面会给出凭据 blob 以及适用于 Claude Desktop、Claude Code 和远程部署的即贴即用配置，每项都带复制按钮。同样的值也会打印到终端作为备用。

在无头机器上或通过 SSH 使用时，改用 auth --terminal 的提示驱动版本。

你会得到一个凭据 blob——包含客户端 ID、客户端密钥和刷新令牌的 base64url 编码 JSON：

eyJ2IjoxLCJjcmVkZW50aWFscyI6eyJ0eXBlIjoib2F1dGhfcmVmcmVzaF90b2tlbiIsImNsaWVu…

把 blob 当作密码对待。 任何持有它的人都能访问你的 Search Console，直到你在 myaccount.google.com/permissions 撤销授权。

它以单个不透明字符串的形式存在，一个值就携带了服务器所需的全部信息——可以直接放入环境变量或 Authorization 请求头，无需在磁盘上保存凭据文件。

OAuth 流程的替代方案

服务账号。 适用于 CI 和团队拥有的资源。在 Google Cloud 中创建一个，然后将其 client_email 作为用户添加到 Search Console 中的资源上（Settings → Users and permissions）。直接对下载的密钥文件进行编码：

base64 -i service-account.json | tr -d '\n'

服务器接受原始服务账号密钥作为 blob——无需任何包装。

现有访问令牌。 设置 {"type":"access_token","access_token":"ya29..."}。无法刷新，因此只适合短时运行的脚本。

权限范围

在 auth 过程中选择只读会请求更窄的权限范围。服务器上的 --read-only 是另一道双保险，会在修改类工具到达 API 之前将其拒绝。

运行方式

本地（stdio）

auth 打印出的配置：

{
  "mcpServers": {
    "google-search-console": {
      "command": "npx",
      "args": ["-y", "google-search-console-mcp"],
      "env": { "GSC_CREDENTIALS": "<your blob>" }
    }
  }
}

配置文件位置：

如果你不想每次都通过 npx 运行，可以正式安装它：

npm install -g google-search-console-mcp

自托管 HTTP

GSC_CREDENTIALS=<blob> npx google-search-console-mcp http --port 8787

提供 POST http://127.0.0.1:8787/mcp 服务。默认绑定到回环地址——如果确实想对外暴露，请有意传入 --host 0.0.0.0，并且如果这样做，请在前面加上 TLS。

除非你明确指定，否则基于浏览器的客户端会被拒绝，因为持有自身凭据的服务器否则会被你访问的任何页面所驱动。普通 MCP 客户端不发送 Origin，不受影响；浏览器客户端则需要列出其来源：

npx google-search-console-mcp http --allowed-origins http://localhost:6274   # MCP Inspector

被拒绝的来源会收到浏览器无法读取的 403（按设计，拒绝时不带 CORS 请求头），因此表现为一般的 CORS 失败——如果浏览器客户端无法连接，请检查服务器的 Origins: 启动行。--allowed-origins '*' 可禁用此检查。

Cloudflare Workers

git clone https://github.com/russjeffery/google-search-console-mcp.git
cd google-search-console-mcp
npm install
npx wrangler deploy

你的端点是 https://google-search-console-mcp.<subdomain>.workers.dev/mcp。

默认情况下 Worker 不存储任何密钥。 每个客户端将自己的凭据 blob 作为 bearer token 发送，因此共享部署永远不会持有任何人的 Google 凭据，同一 URL 的不同用户只能看到自己的资源。

如需私有单租户部署，则改为：

npx wrangler secret put GSC_CREDENTIALS     # your blob
npx wrangler secret put MCP_SHARED_SECRET   # token clients must present

客户端随后发送共享密钥而不是 blob。

wrangler.jsonc 中的可选 vars：

将客户端连接到远程服务器

{
  "mcpServers": {
    "google-search-console": {
      "type": "http",
      "url": "https://your-worker.workers.dev/mcp",
      "headers": { "Authorization": "Bearer <your blob>" }
    }
  }
}

在 Claude 网页版或桌面版界面中，在 Settings → Connectors → Add custom connector 下添加。

为你的部署打印已填好的配置：

npx google-search-console-mcp config --url https://your-worker.workers.dev/mcp

CLI

google-search-console-mcp [command] [options]

  stdio     Run as a stdio MCP server (default)
  http      Run a local Streamable HTTP MCP server
  auth      Guided setup in your browser: OAuth flow, blob, client config
  config    Print client config for existing credentials
  doctor    Verify credentials by calling the API

doctor 是排查问题时的首选工具——它能区分"凭据错误"和"客户端无法启动服务器"两种情况。

选项：--credentials <blob>、--site <siteUrl>、--read-only、--port、--host、--endpoint、--secret、--allowed-origins、--url、--terminal、--no-browser。

--allowed-origins 接受逗号分隔的列表；未设置时仅允许非浏览器客户端。条目不区分大小写匹配，末尾的斜杠会被忽略。

--site 设置默认资源，使工具可以省略 siteUrl——当部署只覆盖一个站点时很方便。

协议支持

2026-07-28 修订版大幅改变了 Streamable HTTP：没有 initialize 握手、没有会话、没有 Mcp-Session-Id、没有 GET 流，params._meta 中的每请求元数据会镜像到 HTTP 请求头中。官方 TypeScript SDK 尚未实现该版本，因此这里的协议层是手写的，并同时支持两个时代。

时代按请求检测：携带现代 _meta 的请求按现代方式处理，initialize 则选择旧版。端点上的 GET 和 DELETE 返回 405，正如修订版所规定。

按规范，请求头校验默认严格。如果客户端发送了现代 _meta 但没有镜像请求头，请设置 MCP_STRICT_HEADERS=0（或 --loose-headers），而不是降级。

关于授权： 规范中的 OAuth 2.1 流程假设服务器是一个带有自有授权服务器的资源服务器。但本服务器改为使用不透明令牌直接携带你的 Google 凭据——规范允许自定义策略，同时这也意味着托管部署不需要保存任何机密，也不需要用户数据库。这样做的代价是：期望自动进行 OAuth 发现的客户端需要像上方所示那样手动配置请求头。

使用数据

Search Console 数据有四个特性最容易导致错误结论。工具描述和随附技能对这些特性做了详细介绍；这里简要说明：

1. 数据滞后约 3 天。 使用 lastDays，工具会选取一个安全的时间窗口。如果时间范围截止到今天，会显示出错误的断崖式下降。

2. 查询数据经过了隐私过滤。 按 query 分组会静默丢弃不常见的查询，因此查询级别的点击量永远不会和资源总数完全一致。这个差距并不代表流量丢失。

3. 排名是相反的。 排名 3 好于排名 8；负向变化反而是改进。compare_search_analytics 会返回一个明确的 improved 标志。

4. 平均值会相互抵消。 总体数字持平，常常掩盖大规模相互抵消的变化。在下结论“什么都没有变”之前，请先按页面或查询进行分组。

配额

• 搜索分析：每个资源每分钟约 1,200 次查询。

• 网址检查：每个资源每天约 2,000 次——这是约束瓶颈。请刻意抽样。

通过 API 无法获取

聚合的 索引覆盖 报告、实时网址测试、请求索引、Core Web Vitals、手动操作、安全问题、链接报告和移除操作在 API 中都没有对应功能，因此这里不包含。单条 URL 的 inspect_url 是处理覆盖范围问题最接近的替代方案。

智能体技能

skills/google-search-console/ 是一个开箱即用的技能，用来教智能体如何用好这些工具——包括上面提到的坑、流量变化的诊断阶梯、寻找机会的启发式方法，以及一张覆盖状态查表。

cp -r skills/google-search-console ~/.claude/skills/

同样的参考素材也可以通过服务器的 gsc://guide/* 资源在运行时获取，因此没有安装该技能的智能体仍然可以阅读。

开发

npm install
npm run build       # compile to dist/
npm run typecheck
npm test
npm run cf:dev      # Worker locally via wrangler

快速手动检查 HTTP 传输：

GSC_CREDENTIALS=<blob> npm run build && node dist/bin/cli.js http &

curl -s http://127.0.0.1:8787/mcp \
  -H 'content-type: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/list' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}' | jq '.result.tools[].name'

故障排查

安全性

• 凭据数据就是你的 Google 访问密钥。不要提交到仓库，也不要把它粘贴到共享文档中。可以在 myaccount.google.com/permissions 撤销。

• HTTP 模式默认绑定到 127.0.0.1，并会把 Origin 与 ALLOWED_ORIGINS 进行校验，以阻止 DNS 重绑定。如果不设置，则不允许任何浏览器来源——请明确列出这些来源，或使用 * 来退出该检查。/health 和 / 是例外，它们不会暴露任何需要认证的能力。

• 共享密钥的校己长度一致，并且比较操作是恒定的时间。

• 默认的 Worker 部署完全不保存任何凭据。

• --read-only / GSC_READ_ONLY=1 会禁止站点地图的修改，这项工作于授予的 OAuth 范围无关。

许可证

MIT