Google Search Console MCP Server

---

一个适用于 Google Search Console 的 MCP 服务。它为 AI 助手提供自然搜索背后的数据和操作手段：查询和网页的表现、距离首页仅差一步的关键词、站点地图的状态，以及特定 URL 是否已编入索引；还可以提交或移除站点地图。

项目缘起。 SEO 的实际工作都发生在 Search Console 中，但它的界面需要频繁点击，数据也很难一眼看出该如何采取行动。最有用的视图——排名接近首页的查询——甚至不是内置报告；你必须自行筛选和查看。此服务将该视图及整个转化漏斗交给 Agent，让 SEO 中繁琐的部分（找出排名差一点的关键词、检查索引状态、保持站点地图正常）能够自动化。

此项目最初用于管理两个网站的 SEO——一个播客和一个个人网站，但这里的内容并不专属于它们。只需将其指向你已验证的任意资源即可。

工具

工具	访问权限	返回内容	API
gsc_list_sites	读取	已验证的资源及权限级别	GET webmasters/v3/sites
gsc_search_analytics	读取	按查询、网页、国家/地区、设备或日期统计的点击次数/展示次数/CTR/排名	POST .../searchAnalytics/query
gsc_striking_distance	读取	平均排名为 8–25 且展示次数足够的查询——优化列表	根据搜索分析计算
gsc_list_sitemaps	读取	已提交的站点地图及其状态、上次下载时间、警告/错误数量	GET .../sitemaps
gsc_submit_sitemap	写入	向 Google 提交/通知站点地图	PUT .../sitemaps/{feedpath}
gsc_delete_sitemap	写入，有破坏性	从 Search Console 注销站点地图	DELETE .../sitemaps/{feedpath}
gsc_inspect_url	读取	索引状态、上次抓取时间、规范 URL、移动设备/富媒体结果判定	POST searchconsole/v1/urlInspection/index:inspect

每个工具都带有 MCP 读取/写入注释，因此客户端在调用前可以区分两个写入工具和五个只读工具。读取工具设置为 readOnlyHint: true；gsc_submit_sitemap 是非破坏性写入；gsc_delete_sitemap 设置为 destructiveHint: true。

列表工具的 row_limit / limit 默认值较低（25），以保持响应精简——Agent 会按每次响应消耗令牌。

身份验证

此服务使用 OAuth 已安装应用凭据（保存的刷新令牌），而不是服务账号或 API 密钥。它从以下位置读取凭据：

~/.config/gws/searchconsole_credentials.json

该文件采用 google-auth 的 Credentials.to_json() 格式：包含 client_id、client_secret、refresh_token 和 scopes。服务会直接使用 fetch 向 Google 的令牌端点刷新短期访问令牌，无需依赖庞大的 googleapis。

如果你还没有此文件，可以自行创建：

1. 在 Google Cloud Console 中，创建一个类型为 桌面应用 的 OAuth 客户端，并下载其 client_secret.json。
2. 在该项目中启用 Search Console API。
3. 运行已安装应用 OAuth 流程，请求所需的 scope（见下文），并将生成的凭据保存到 ~/.config/gws/searchconsole_credentials.json。任何标准的 google-auth-oauthlib 已安装应用代码片段都适用——大约十行，并会打开浏览器供你点击一次授权。

特意让此路径保持一致：如果你已在该位置为其他工具保存了 Search Console 凭据，此服务会复用它，而不会要求你另外生成一份。

Scope：只读与完整权限

• 读取工具使用 https://www.googleapis.com/auth/webmasters.readonly。
• 写入工具（gsc_submit_sitemap、gsc_delete_sitemap）和 URL 检查需要完整的 https://www.googleapis.com/auth/webmasters scope。

如果你保存的凭据只有只读 scope，读取工具仍可正常工作，而写入工具会返回明确的“使用完整 scope 重新生成凭据”错误，而不是含糊的 403。使用完整 scope 重新生成凭据会原地更新同一文件；读取工具在此期间仍可继续工作。

如果你不使用默认位置，可将 GSC_CREDENTIALS_PATH 设置为其他凭据文件的路径。

无凭据时启动

即使不存在凭据，服务也会启动并响应 tools/list，以便 MCP 检查器查看其信息。之后调用工具时会返回设置说明（启动时输出到 stderr，也会作为工具结果返回）。stdout 专用于 MCP 传输，并会保持干净。

设置

1. 在 Search Console 中验证你的资源

在 search.google.com/search-console 添加你的网站。推荐使用 网域资源（通过 DNS TXT 记录验证），它涵盖 http/https 及所有子域名。记下资源的准确字符串——gsc_list_sites 会将其显示为 sc-domain:example.com（网域）或 https://example.com/（网址前缀）。

2. 生成凭据

按照 身份验证 部分的说明创建 ~/.config/gws/searchconsole_credentials.json；如果要使用写入和 URL 检查工具，请请求完整的 webmasters scope。

3. 配置 MCP 客户端

Claude Code

添加到你的 .mcp.json：

{
  "mcpServers": {
    "gsc": {
      "command": "npx",
      "args": ["-y", "@conorbronsdon/gsc-mcp"]
    }
  }
}

Claude Desktop

添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "gsc": {
      "command": "npx",
      "args": ["-y", "@conorbronsdon/gsc-mcp"]
    }
  }
}

凭据位于默认路径时，无需 env 块。如果凭据位于其他位置，请设置 GSC_CREDENTIALS_PATH。

4. 验证

向助手询问：“列出我的 Search Console 资源”，然后询问：“显示该资源过去 28 天内接近首页的关键词。”

限制

请阅读以下内容，了解这些数字的含义，以及此工具能做什么、不能做什么。

• 按设计，不提供请求编入索引的工具。 Search Console 的“请求编入索引”按钮没有公开 API。Google 的 Indexing API 仅支持 JobPosting 和 BroadcastEvent 页面，不支持普通内容；将其用于普通页面会违反其条款。因此，这里有意不提供“请求 Google 将此页面编入索引”的工具；对于普通页面，只能在 Search Console 界面中手动点击请求编入索引。gsc_submit_sitemap 是受支持且由 API 提供支持的促使抓取方式。
• 数据延迟约 2–3 天。 Search Analytics 不是实时数据。请将日期范围的结束时间设为今天之前几天，否则最近几天的数据会为空。
• searchAnalytics 每次调用都有上限。 此处的 row_limit 上限为 1000（API 允许通过分页获取 25,000 条）；若要获取大量数据，请使用 start_date／维度筛选进行分页，而不是一次性请求所有数据。
• 近排名机会在客户端计算。 它最多获取 1000 条查询行，然后筛选出目标排名区间。在排名查询数以千计的网站上，区间视图反映的是点击量最高的前 1000 条，而非全部长尾数据。
• URL 检查有速率限制且速度较慢。 Google 对 URL Inspection API 设定了较低的每日配额，每次调用可能需要一两秒。请检查你关注的特定 URL，不要对整个站点地图循环调用。
• 不提供添加／移除资源的工具。 验证资源是一个有状态且容易出错的流程（DNS TXT、元标记、文件上传），不适合通过单次工具调用完成。请在 Search Console 界面中添加并验证资源；此服务仅适用于你已验证的资源。
• 适用一般 API 配额。 HTTP 429 时，服务会返回明确的错误。请适度控制 row_limit 和检查量。

开发

git clone https://github.com/conorbronsdon/gsc-mcp.git
cd gsc-mcp
npm install
npm run build
npm test

本地运行：

npm start

测试会模拟 fetch，不会发起网络请求。

贡献

欢迎提交问题和拉取请求。如果有值得封装为工具的 Search Console 端点，请提交问题，说明它应返回什么内容，以及对应的端点。请确保接口约定准确：读取工具保持只读，写入工具带有正确的注释，响应保持简洁。

套件中的其他服务

Search Console 是更广泛的 Google 数据栈中的一类凭据。其他同系列服务各自使用独立的身份验证方式：

数据	服务
Google Workspace（Gmail、Calendar、Drive、Sheets、Docs、Tasks）	gws-mcp-server — 同样采用精简且精选的方式：接口范围有限，每个工具都声明副作用
YouTube Analytics	yt-analytics-mcp — 所有者端的观看时长、留存率、流量来源和播放列表指标；只读
Google Analytics 4	googleanalytics/google-analytics-mcp — Google 官方服务，只读
BigQuery	googleapis/mcp-toolbox — Google 官方服务

这里的服务不会共用令牌：此服务使用 webmasters OAuth 凭据，Workspace 使用 gws auth login，YouTube Analytics 使用 yt-analytics.readonly OAuth 凭据，GA4 使用范围为 analytics.readonly 的 Application Default Credentials。

关于

由 Conor Bronsdon 构建并维护。我主持 Chain of Thought 播客，内容涵盖 AI 基础设施、开发者工具，以及从业者如何实际使用这些工具。我构建此项目，是为了将 SEO 工作融入运行播客和网站的 Agent 工作流中。

配套工具：

• op3-mcp：通过 OP3 查看播客分析数据，包括下载量、地理位置、应用和单集明细。
• podcast-benchmark：根据公开数据指标，将你的节目与同类节目进行对比。
• Transistor MCP：Transistor.fm 的官方 MCP 服务。支持单集管理、发布和分析。
• substack-mcp：在 Substack 上阅读文章并管理草稿，适用于 Agent 工作流。
• ai-tools-for-creators：为以创意为生的人精选的 AI 技能和 MCP 服务列表。

更多信息请访问 chainofthought.show，或关注 X。

---

免责声明

这是一个独立的个人项目，与 Google LLC 无关，也未获得其赞助或认可。文中所有观点均为我个人观点。

许可证

MIT