Google Search Console

google-search-console-mcp

一个适用于 Google Search Console 的模型上下文协议（MCP）服务。Google Search Console 能告诉你 Google 如何看待你的网站——此服务可以读取相关信息并进行设置。

MCP 客户端（如 Claude Code、Claude Desktop 或 Codex）可以用它创建资源并验证所有权、提交和刷新站点地图、查询任意 URL 的索引状态，以及查询完整的效果报告——不可逆操作会先交由人工确认，也可以完全关闭写入工具。

21 个工具只是上限，并非必须全部启用：设置 GSC_ALLOW_TOOLS=essential，即可改为注册经过筛选的 5 个工具。与 21 个工具相比，模型能更可靠地从 5 个工具中选出合适的工具——详见选择要加载的工具。

有何不同

它能真正创建可用的资源。 创建资源需要按固定顺序完成四个步骤——获取验证令牌、将其放入 DNS 或网页中、验证所有权、添加资源——而 Google 的 API 并不强制执行这个顺序。先调用 sites.add 会_成功_，并留下一个出现在所有列表中、但访问任何数据都会返回 403 的资源。这看起来像是权限问题，其实并不是。setup_site 会报告缺少哪个步骤，并提供可直接粘贴的确切 DNS 记录。只提供 sites.add 的服务只能添加已由用户手动验证的资源。

三个 API，而非一个。 Search Console v1 有十个方法，但不包含所有权验证。Site Verification 是一项独立服务，使用自己的 scope、自己的主机，并且对同一个站点采用不兼容的命名方式——其中的 sc-domain:example.com 对应 {type: INET_DOMAIN, identifier: example.com}；直接传入资源名称也会被接受，并验证一个名为 sc-domain:example.com 的域名。Indexing API 则是第三个 API。三个 API 均受支持，它们之间的转换逻辑位于 src/site-identity.ts 中。

数据准确无误。 搜索分析结果以表格形式返回总计值，其中 CTR 根据总计值计算，而非对各行取平均；平均排名则按展示次数加权。如果不加权，一千个排名第 80 位的低频查询会把资源真实的平均排名 12 拉高到 90 多。结果还会明确说明，使用查询维度时，各行之和不会等于资源总计——Google 为保护匿名性会隐去低频查询，通常占全部展示次数的三分之一甚至更多；如果不加上这个说明，用户就会引用这个数字。

它了解这些 API 的易错之处。 https://example.com/ 末尾的斜杠不可省略，否则会返回 403；同一站点的域名资源和网址前缀资源是两个不同的资源，数据也不同，因此系统会拒绝裸主机名，而不是猜测用户的意图；日期按太平洋时间计算，因此用 UTC 计算的 last7days 会请求 Google 没有数据的一天；hour 维度在没有 dataState: HOURLY_ALL 时会静默返回空结果；Google 会完全省略空数组，因此新凭据的资源列表会以 {} 返回；而 Indexing API 对任何已拥有的网址都会返回 200，但只会处理 JobPosting 和 BroadcastEvent 页面。

要求

• Node.js 22 或更高版本（或容器映像）
• Google 凭据——服务账号密钥、OAuth2 刷新令牌或应用默认凭据
• 在 Google Cloud 项目中启用你计划使用的 API：Search Console API，以及单独启用的 Site Verification API 和 Indexing API

配置

服务无需凭据即可启动并列出其工具；之后的每次调用都会返回设置说明，而不是 Google 错误。这是有意为之，方便注册表和沙盒检查器检查它。

变量	描述
GSC_SERVICE_ACCOUNT_KEY	服务账号密钥，格式为原始 JSON 或 Base64 编码的 JSON
GSC_SERVICE_ACCOUNT_KEY_FILE	服务账号密钥文件的路径。与上述变量二选一——两者同时设置会报错
GSC_CLIENT_ID	OAuth2 客户端 ID
GSC_CLIENT_SECRET	OAuth2 客户端密钥
GSC_REFRESH_TOKEN	OAuth2 刷新令牌。必须同时设置全部三个 OAuth2 变量
GOOGLE_APPLICATION_CREDENTIALS	应用默认凭据；未设置 GSC_ 凭据时使用
GSC_SITE_URL	默认资源，例如 sc-domain:example.com 或 https://example.com/。设置后，所有位置的 site_url 均可省略
GSC_ALLOWED_SITES	此服务允许访问的资源，以逗号分隔；其他资源一律拒绝
GSC_READ_ONLY	true（或 1/yes）仅注册 12 个读取工具
GSC_ALLOW_TOOLS	以逗号分隔的工具名称、list_* 前缀或 essential
GSC_DENY_TOOLS	格式相同；从允许列表中排除相应工具
ELICITATION	false 会用两次调用的令牌机制取代审批对话框。没有 GSC_ 前缀

凭据按上述顺序尝试——显式指定的凭据优先于环境凭据。不完整的 OAuth 三元组会导致启动错误，而不会回退到应用默认凭据，因为这种回退会悄悄地让服务以机器当前登录账号的身份运行。

使用哪种凭据

推荐使用服务账号：它只能访问你明确添加给它的资源，撤销它也不会影响任何人的 Google 账号。在 Search Console 的“设置”→“用户和权限”下添加其 client_email，或者使用 verify_site 将资源所有权授予它。请注意，Indexing API 要求的是所有者权限，而非完整用户权限。

OAuth2 刷新令牌会以授权者的身份运行，并能访问授权者可见的所有内容。其作用域在授权时便已确定，之后无法扩大。

选择要加载的工具

每个可见工具都会在每次请求中占用上下文，而模型从 5 个工具中选出正确工具的可靠性，远高于从 21 个中选出。两个变量可以缩小列表：

GSC_ALLOW_TOOLS=essential          # the curated five
GSC_ALLOW_TOOLS='list_*,get_site'  # exact names, or one trailing *
GSC_DENY_TOOLS='delete_*'          # subtracted from whatever allow left

essential 包含 list_sites、get_site、list_sitemaps、 query_search_analytics 和 inspect_url——查看一个资源所需的一切，且不会对其进行任何更改。

如果某个条目与任何工具都不匹配，服务就会停止，并列出实际名称。忽略拼写错误本会导致某个工具从 tools/list 中消失，却没有任何信息指出原因，而且没人会追溯工具缺失是否与环境变量有关。

如果你同时运行多个此类服务，mcp-hub 是另一种解决方案——它的 /hub 端点会用 6 个元工具替换所有服务的工具。

缩小列表也会缩小所需凭据的范围：此服务请求的 OAuth 范围根据实际注册的工具生成，因此，未获准使用 Indexing 工具的服务绝不会请求 Indexing 范围。

安装

Claude Code

claude mcp add google-search-console -- npx -y @ni-c/google-search-console-mcp

Claude Desktop

{
  "mcpServers": {
    "google-search-console": {
      "command": "npx",
      "args": ["-y", "@ni-c/google-search-console-mcp"],
      "env": {
        "GSC_SERVICE_ACCOUNT_KEY_FILE": "/path/to/key.json",
        "GSC_SITE_URL": "sc-domain:example.com"
      }
    }
  }
}

Codex

[mcp_servers.google-search-console]
command = "npx"
args = ["-y", "@ni-c/google-search-console-mcp"]

[mcp_servers.google-search-console.env]
GSC_SERVICE_ACCOUNT_KEY_FILE = "/path/to/key.json"
GSC_SITE_URL = "sc-domain:example.com"

Docker

docker run --rm -i \
  -v /path/to/key.json:/key.json:ro \
  -e GSC_SERVICE_ACCOUNT_KEY_FILE=/key.json \
  -e GSC_SITE_URL=sc-domain:example.com \
  ghcr.io/ni-c/google-search-console-mcp

通过 mcp-hub

无法启动本地进程的客户端——ChatGPT connectors、Claude on the web、 Cursor、LibreChat——可以通过 mcp-hub 访问 google-search-console-mcp：一个容器通过 Streamable HTTP 提供多个 stdio MCP 服务，并在单个密码后提供 OAuth 2.1 登录，还为无法使用 OAuth 的客户端提供长期令牌。它的 /hub 端点会将所有服务置于 6 个元工具之后，因此，一个连接器即可访问所有服务，而无需在模型的上下文中放入 N×工具架构；它还同时支持两个协议修订版——此服务提出的问题会经由它传递给另一端的人。

它的 /config/mcp.json 使用 Claude Code 的格式，因此配置条目就是你已有的那一条：

{
  "mcpServers": {
    "google-search-console": {
      "command": "npx",
      "args": ["-y", "@ni-c/google-search-console-mcp"],
      "env": {
        "GSC_SERVICE_ACCOUNT_KEY": "…",
        "GSC_SITE_URL": "sc-domain:example.com"
      }
    }
  }
}

这里的 allowTools 和 denyTools 是 hub 针对每个服务设置的自有过滤器，这与 env 中的 *_ALLOW_TOOLS 并不是一回事——两者的区别及其容易引发的错误，详见客户端指南。

工具

设置 GSC_SITE_URL 后，所有可接受 site_url 的工具都可以不传此参数。

每个工具都声明了 outputSchema，并在文本块旁通过 structuredContent 返回结果，因此客户端无需解析文本即可使用结果。query_search_analytics 会在文本块中保留渲染后的表格，并将行本身放在结构化部分；原本只有 6 个工具以句子形式作答，现在它们也会返回字段。

所有报告 Google 数据的工具都会包含 untrusted: true 和 source: "search-console" 字段。“这只是搜索数据”恰恰是错误的直觉：搜索查询是公众输入 Google 的字符串，而页面标题来自被抓取的网站。以下 6 个工具不带此标记，因为它们的回答是此服务收到的资源信息或已确认的事实：add_site、delete_site、submit_sitemap、submit_sitemaps、delete_sitemap 和 unverify_site。

属性和所有权

工具	功能说明
setup_site	报告属性缺少四个设置步骤中的哪些步骤，以及需要添加的 DNS 记录或元标记。不做任何更改
list_sites	此凭据可以查看的所有属性及其权限级别
get_site	单个属性——用于确定两种拼写中哪一种存在
add_site	添加属性。不会验证所有权
delete_site 👤	移除属性及其历史记录
list_verified_sites	此凭据已证明所有权的站点及其所有所有者
get_verified_site	通过不透明资源 ID 获取其中一个
get_verification_token	获取令牌及其确切放置位置。不声明任何内容
verify_site	检查已放置的令牌并记录所有权
unverify_site 👤	放弃所有权
update_site_owners	替换所有者列表。method: "patch" 使用 PATCH，效果完全相同

站点地图

工具	功能说明
list_sitemaps	已提交的站点地图，包括下载时间、网址数量和错误
get_sitemap	单个站点地图——用于查看提交内容中实际出现的错误
submit_sitemap	提交或刷新一个站点地图。没有单独的更新调用
submit_sitemaps	一次最多提交 50 个，并返回每项结果
delete_sitemap 👤	移除一个

搜索分析和索引

工具	功能说明
query_search_analytics	效果报告：按任意维度统计点击次数、展示次数、点击率和排名，并支持筛选条件和相对时间段
inspect_url	查看 Google 对单个网址的了解情况——索引状态、规范网址、抓取时间和富媒体结果
inspect_urls	最多检查 20 个网址，并简要汇总判定结果
get_indexing_status	某个网址的索引 API 通知历史记录
request_indexing	通知 Google 某个网址已更改。仅对 JobPosting 和 BroadcastEvent 页面生效

有意不提供的功能

urlTestingTools.mobileFriendlyTest 仍在 Google 的发现文档中，但其背后的服务已于 2023 年 12 月关闭。针对它的工具只会返回错误，因此没有提供。

安全

四项操作需要由人确认。 delete_site、delete_sitemap、 unverify_site 和 update_site_owners 会通过 MCP elicitation 发起真正的对话框（客户端支持时）——模型无法代替用户作出确认。如果客户端不支持，它们会拒绝首次调用，并返回一个绑定到这些确切参数的短期令牌，同时明确说明这一点，而不会暗示有人已经批准。无论哪种情况，批准都绑定到相应的资源，因此为一个资源签发的批准无法用于另一个资源。update_site_owners 也在此列，因为它接收的列表就是操作完成后的完整所有者列表——一次格式正确的调用就会移除其他所有人，而这里没有任何操作可以将他们加回来。 ELICITATION=false 会主动使用回退路径；它绝不会移除这项保护。请参阅 请求用户确认。

来自 API 的所有内容都标记为不可信。 搜索查询是公众输入到 Google 的字符串；网页标题和抓取诊断信息来自运行被抓取网站的人。如果有人想让模型按照自己的指示行动，可以把指示放进网页标题，然后等它被抓取。确认提示词的两句话仅由服务派生的值构成；站点地图 URL 或所有者列表会作为数据引用在下方。

允许列表没有例外。 GSC_ALLOWED_SITES 会在工具指定资源时强制执行，也会分别应用于两种未指定资源的情况：Indexing API 工具会像 Search Console 确定资源范围一样，将页面 URL 与列表匹配；验证工具则会先将不透明的资源 ID 解析为资源，再执行操作。两个列表接口都会筛选出允许列表中的项目，并说明有多少条目被隐藏。

只读限制深入工具层之下。 GSC_READ_ONLY=true 不仅不会注册写入工具，还会请求 webmasters.readonly，而不是 webmasters，因此即使工具试图写入，也无法完成。

凭据绝不会泄露到输出中。 凭据会在启动后从环境中删除，不会发送给重定向目标；被拒绝的值只会被描述，而不会原样回显——即使是不小心粘贴到 GSC_ALLOW_TOOLS、GSC_SITE_URL 或 ELICITATION 中的密钥也是如此，访问令牌本身也不例外，它会在成为请求标头之前接受检查。

Google 返回的内容会经过结构校验。 响应状态会在读取响应正文之前确定；结果承诺的每个字段都会在边界处检查——不是对象的行会被丢弃，值为 null 的站点块不算作站点，空的 200 响应会被视为空记录——输出文本中的控制字符也会被剔除。结果会在两种通道中分别受到配额限制，调用方提供的字符串有长度上限，批量调用会在两分钟后停止并说明已完成的进度。请参阅安全性。

文档

完整指南、工具参考和安全说明请参阅 google-search-console-mcp.ni-c.de（源文件位于 docs/）。

开发

npm install
npm test            # no network — every test runs against a stubbed fetch
npm run lint
npm run build

请参阅 CONTRIBUTING.md。

发布

更新 CHANGELOG.md，在 package.json 和 server.json 中提升版本号，然后 推送一个签名标签：

git tag -s v0.1.0 -m 'v0.1.0' && git push origin main v0.1.0

release.yml 会运行测试套件，通过可信发布者机制将软件包发布到 npm，将多架构镜像推送到 GHCR，并更新 MCP 注册表条目。

贡献

欢迎提交问题、参与讨论和发起拉取请求——请参阅 CONTRIBUTING.md。如需报告漏洞，请使用 私密报告渠道， 而不是公开提交问题；相关政策见 SECURITY.md。

许可证

MIT © Willi Thiel