Google Search Console

短片展示的是使用示例数据的托管版 getmcpads。从创意图库和提醒，到 Google Sheets 导出和批量发布，其 MCP Apps 均属于托管产品。此代码库提供独立的原生 API 工具。

20 个只读工具 · 专为只读而设计。

使用您自己的平台凭据，在本地运行，并连接支持 stdio MCP 的客户端，例如 Claude Desktop、Claude Code 或 Cursor。您的请求会直接发送到平台。如需托管连接（包括受支持的 ChatGPT 配置），请使用托管选项。

更新内容

v2.1.1：Zod 4 安全更新 · 2026 年 10 月 26 日

• 将 zod 更新至 4.6.7。4.6.6 之前的所有 Zod 版本都受高危安全公告 GHSA-mrhx-c7xc-m3w5 影响：验证超出大小限制的集合可能耗尽内存，且没有任何 Zod 3 版本包含此修复。npm audit --omit=dev 再次显示无漏洞。
• 保持 Zod 3 的验证行为。参数默认值在使用前仍会经过验证和补全，因此省略的对象仍须提供必填字段。
• 参数可选或有默认值时，保留其自身的描述。Zod 4 仅在包装后的 schema 上存储描述，否则共享的回退描述可能会覆盖它。
• 通过 MCP 发布的工具名称、参数和描述均未更改。server-card.json 已使用 Zod 4 的 JSON Schema 输出重新生成，其中部分约束的表示方式有所不同。

此前的版本

版本	日期	主要更新
2.1.0	2026 年 10 月 23 日	站点允许列表和已撤销令牌处理
2.0.1	2026 年 9 月 23 日	恢复公开代码库
2.0.0	2026 年 9 月 20 日	网关同步和安全修复
1.1.0	2026 年 9 月 13 日	平台功能同步和质量契约
1.0.2	2026 年 8 月 30 日	通过 MCP 公布软件包版本。
1.0.1	2026 年 8 月 30 日	为官方 MCP Registry 添加 server.json 和 mcpName，名称为 com.getmcpads/google-search-console。
1.0.0	2026 年 8 月 29 日	首次开源发布

完整更新日志 · 所有版本

源同步：SOURCE_SYNC.md。

升级说明

需要使用 Node.js 22.23.4、24.22.1 或 26.12.1，或这些版本线中的更新版本。较旧版本缺少 2026 年 10 月的安全修复，服务器在这些版本上启动时会在 stderr 中打印警告。CI 覆盖 Node 22、24 和 26。

此版本不会对配置造成破坏性变更。已宣布在 3.0.0 中进行一项变更：GSC_SITE_URLS 在 2.x 中为可选项，在 3.0.0 中将变为必填项。设置后，每个工具都只能访问列出的资源，并且 GSC_SITE_URL 必须是其中之一。未设置时，服务器会像以前一样启动，并在 stderr 中打印一行建议。20 个工具、它们的架构以及有界报告限制均保持不变。

安装此版本

这是 GitHub 源码版本。npm 和 MCP Registry 版本会单独发布。以下命令会选择此确切版本；本文档后面未固定版本的 npx 示例会选择 npm 上当前可用的版本。

git clone --branch v2.1.1 --depth 1 https://github.com/get-mcp-ads/google-search-console-mcp-server.git
cd google-search-console-mcp-server
npm ci
npm run build

配置 MCP 客户端，使其使用 node 运行 dist/cli.js 的绝对路径，并使用下文说明的平台凭据。

更倾向于托管连接？ 通过托管服务 getmcpads 使用 Google Search Console。连接你的账号，选择助手可访问的数据，并使用托管 MCP 连接。当前功能和方案请参阅网站。

你将获得

20 个只读工具	Search Analytics、站点、站点地图、URL Inspection，以及基于这些内容构建的分析
SEO 分析，而不只是 API 封装	关键词蚕食检测、查询聚类、时期之间的增长与下滑、索引状态监控列表、大型站点抽样计划
7 个资源	模型可读取的实时目录：指标、维度、过滤器、兼容性规则、8 个工作流方案、只读操作指南
配额防护	每次 URL Inspection 调用最多检查 10 个 URL，因此一次探索性问题不会耗尽一天的配额
完全不写入数据	这不是一个开关，而是代码本身的属性。见下文

除了获取数据行，它还能做什么

Search Console 能回答有关数据行的问题。大多数实际问题都关乎变化：哪些查询的表现下滑了，哪些页面在争夺相同的搜索词，索引状态是否正在发生偏移。

这些工具会完成这项工作，而不是把它留给模型：

工具	回答的问题
gsc_detect_cannibalization	哪些页面在争夺相同的查询
gsc_find_losses_gains	两个时期之间哪些方面有所增长或下滑
gsc_cluster_queries	哪些查询具有相同的意图
gsc_compare_search_types	网页、图片、视频和新闻之间有何差异
gsc_analyze_search_appearance_trends	富媒体搜索结果如何变化
gsc_indexation_watchlist	哪些 URL 的索引判定发生了变化
gsc_plan_large_site_sampling	无法检查所有 URL 时，应检查哪些 URL

---

在相信某个数字之前，有一点需要了解

Search Console 返回的是排名前 N 的数据，而不是整个站点的总数据。

使用 query 或 page 等维度进行查询时，API 会按点击次数排序，并在行数上限内返回排名最高的数据行。将这些行的点击次数相加，并不能得出整个站点的总数：长尾数据缺失，而对于大型站点，长尾流量可能占大部分。

要获取真实总数，请在查询时不使用维度。要比较不同时间段，应确保比较条件一致：维度相同、行数上限相同、搜索类型相同。

gsc_query_search_analytics 会报告实际返回的数据，而 gsc_validate_query 会在查询执行前检查组合是否有效。但要避免算术错误，责任在你自己；这是 Search Console 分析中最常见的错误。

还有两个值得牢记的限制：

• **历史数据大约保留 16 个月。**更早的数据已不存在，而不是加载较慢。
• 数据大约需要三天才会稳定。gsc_get_data_freshness 会告诉你哪些数据已经最终确定。

---

只读，以及为何始终如此

这里没有写入工具，也没有任何能添加写入工具的环境变量。Search Console API 可以提交和删除站点地图、添加和移除资源，以及请求编入索引。此服务不提供其中任何功能。

它请求的授权范围也体现了这一点：webmasters.readonly，而不是 webmasters。即使模型尝试写入，令牌也无法执行。

我们的广告平台服务支持写入操作，也确实需要这些操作，但它们都必须经过预览： Meta Ads · Google Ads · TikTok Ads

getmcpads.com 上的托管版本也遵循同一规则：Search Console 在那里同样保持只读。

---

获取凭据

只需获取 3 个值，获取一次即可。

1. OAuth 客户端

在 Google Cloud 项目中启用 Google Search Console API，然后在 APIs & Services → Credentials 下创建 OAuth 客户端。本地使用请选择 Desktop app。记下 client ID 和 client secret。

2. 刷新令牌

使用拥有或可读取相应资源的 Google 账号登录，运行一次 OAuth 授权流程，并保存 refresh token。只请求 webmasters.readonly，无需其他权限。

📖 Google OAuth for installed apps

刷新令牌不会过期。 请使用专门用于此服务的 OAuth 客户端，这样便可单独撤销它。

如需快速试用，也可以将 GSC_ACCESS_TOKEN 设为短期令牌，但它会在 1 小时内过期，不适合日常使用。

如果你不想为了一个资源配置 OAuth 客户端， getmcpads.com 可以代你处理授权流程，并通过托管端点提供相同的工具。

3. 站点 URL，可选

设置 GSC_SITE_URL，即可避免每次调用时都传入站点 URL。两种资源形式均可使用：

资源类型	值
URL-prefix	https://example.com/（结尾的斜杠很重要）
Domain	sc-domain:example.com

使用 gsc_list_sites 列出你有权访问的资源，并将 gsc_health_check 作为首次调用。 它会验证凭据，但不会打印任何机密信息。

---

设置

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS） 或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "search-console": {
      "command": "npx",
      "args": ["-y", "@getmcpads/google-search-console-mcp-server"],
      "env": {
        "GSC_CLIENT_ID": "your-client-id",
        "GSC_CLIENT_SECRET": "your-client-secret",
        "GSC_REFRESH_TOKEN": "your-refresh-token",
        "GSC_SITE_URLS": "sc-domain:example.com"
      }
    }
  }
}

重启 Claude Desktop。向它提问：“我们上个月失去了哪些查询？”。

Claude Code

claude mcp add search-console --env GSC_CLIENT_ID=... --env GSC_CLIENT_SECRET=... --env GSC_REFRESH_TOKEN=... -- npx -y @getmcpads/google-search-console-mcp-server

Cursor

在项目中创建 .cursor/mcp.json，格式与上面的 Claude Desktop 配置相同。

从源代码运行

git clone https://github.com/get-mcp-ads/google-search-console-mcp-server.git
cd google-search-console-mcp-server
npm install && npm run build
cp .env.example .env   # then fill in your credentials
npm start

配置

变量	默认值	含义
GSC_CLIENT_ID	无	OAuth 客户端 ID
GSC_CLIENT_SECRET	无	OAuth 客户端密钥
GSC_REFRESH_TOKEN	无	来自授权流程
GSC_ACCESS_TOKEN	无	上述 3 个值的替代项，会在 1 小时内过期
GSC_SITE_URL	无	可选的默认资源
GSC_SITE_URLS	未设置	推荐设置。逗号分隔的资源列表，所有工具仅限访问这些资源；请完全按照 Search Console 中显示的内容填写。未设置时，可访问凭据能够触达的所有资源。3.0.0 版本中必填
LOG_LEVEL	info	debug、info、warn、error

必须设置 3 个 OAuth 值，或设置 GSC_ACCESS_TOKEN。两者都未设置时，服务会拒绝启动。

npm run doctor

---

工具

下方列出了所有工具。完整的参数和输出架构请参阅 server-card.json。

20 个读取工具

工具	用途
gsc_list_sites	列出使用当前凭据可访问的所有 Google Search Console 资源。
gsc_get_site	获取一个 Search Console 资源及其确切权限级别（只读 sites.get）。
gsc_health_check	验证 Google Search Console 只读身份验证、可见资源、配置的默认网站和权限级别，不会暴露令牌。
gsc_query_search_analytics	查询 Google Search Console Search Analytics。
gsc_inspect_url	检查网址的 Google 索引状态、抓取信息、移动设备易用性、AMP 和富媒体搜索结果。
gsc_bulk_inspect_urls	以保守的顺序限制检查多个网址，并返回规范化的网址检查结果。
gsc_list_sitemaps	列出为某个 Search Console 资源提交的站点地图，包括处理状态及已提交／已编入索引的数量。
gsc_get_sitemap	根据完整 Feed 路径获取一个已提交的站点地图，包括类型、抓取状态、警告／错误以及已提交／已编入索引的内容总数。
gsc_get_sitemap_health	返回经过扩充的只读站点地图健康摘要，包括状态总数、已提交／已编入索引的内容数量、警告和错误。
gsc_compare_search_types	比较 Search Console 不同搜索类型的效果：网页、图片、视频、新闻、Discover 和 Google 新闻。
gsc_get_data_freshness	通过查询近期每日数据行，检测 Search Analytics 数据的最新日期。
gsc_monitor_indexation_freshness	只读监控快照，包含 Search Analytics 数据新鲜度、站点地图索引总数，以及可选的小规模网址检查样本。
gsc_track_sitemap_deltas	只读站点地图变化跟踪器。
gsc_analyze_search_appearance_trends	通过 Search Analytics 的 searchAppearance 维度分析结构化数据和富媒体搜索结果的趋势信号（如果 GSC 提供该维度）。
gsc_plan_large_site_sampling	根据站点地图风险信号和 Search Analytics 页面效果，为大型网站制定只读网址检查抽样计划。
gsc_indexation_watchlist	针对关键网址的只读网址检查监控列表。
gsc_find_losses_gains	比较两个时间段的查询或页面效果，并返回点击次数／展示次数／点击率／排名变化。
gsc_cluster_queries	根据简单的词元和意图信号对 Search Console 查询进行聚类：品牌／非品牌、问题、类别和主题词元。
gsc_detect_cannibalization	检测 Search Analytics 查询-页面数据行中多个页面争夺点击次数／展示次数的查询。
gsc_validate_query	执行前验证 Search Console 的指标／维度／搜索类型组合。

7 个资源

URI	内容
gsc://manifest	此服务提供的内容，以及应首先运行的工具
gsc://metrics	8 个 Search Analytics 指标，包含原始指标和派生指标
gsc://dimensions	7 个维度及其适用范围
gsc://filters	5 个过滤运算符及其接受的值
gsc://compatibility	不同维度适用的搜索类型和数据状态
gsc://recipes	8 个分步工作流
gsc://p2-readonly-playbooks	监控操作手册及其不变量

---

安全

• 客户端密钥和刷新令牌绝不会被记录，无论日志级别如何，也不会写入磁盘。
• 已撤销的刷新令牌只会报告一次。 当 Google 返回 invalid_grant 时，之后的每次调用都会返回相同的消息以及重新授权的步骤，并且服务在重启前不会再向 Google 请求令牌。
• 可以限制资源。 设置 GSC_SITE_URLS 后，调用若指定其他资源，会在发出任何请求前被拒绝，且 gsc_list_sites 只会列出获准的资源。
• 只会连接三个主机：用于 API 的 searchconsole.googleapis.com 和 www.googleapis.com，以及用于刷新令牌的 oauth2.googleapis.com。如果源码中出现第四个主机，测试就会导致构建失败。
• 不会跟随重定向获取内容。 每个出站调用都会设置 redirect: "error"，因此重定向无法将 Bearer 令牌或客户端密钥转发到其他主机。如果任何 fetch 调用未设置此项，测试就会导致构建失败。
• 作用域为 webmasters.readonly。 令牌本身无法执行写入操作。
• 不进行遥测。 服务除 Google 外不会发起任何网络请求。

完整政策：SECURITY.md。

---

想要托管式、多平台版本？

如果你想使用此源码而不运行本地服务，可以试用托管版 Search Console。 getmcpads 还可通过一个 MCP URL 连接广告服务、Search Console 和 GA4。 网站列出了可用源码和方案限制；仍需连接账号。

1. 按照 Search Console 连接指南操作。
2. 选择助手可以读取的账号或资源。
3. 连接 Claude、 ChatGPT 或 Codex。
4. 尝试进行只读检查：“找出哪些页面和查询导致自然点击量发生变化。指出缺失的数据，不要做任何更改。”

在选择付费方案前，请查看当前托管工具目录 和定价。 此 Apache 2.0 适配器仍可使用你自己的凭据独立运行。

---

贡献

欢迎提交问题和拉取请求。请参阅 CONTRIBUTING.md。 报告任何安全相关问题前，请先阅读 SECURITY.md。

许可证

Apache License 2.0。另请参阅 NOTICE。

Google 和 Google Search Console 是 Google LLC 的商标。 本项目与 Google LLC 无关，也未获得其认可或赞助。 这是一个独立的公共 API 客户端。

MCP 契约和桌面端捆绑包

每个工具都会声明读写注解、参数说明和结构化输出架构。成功调用会将有效载荷放在 structuredContent.result 中；错误会保留 isError: true。生成的服务卡片仅包含定义。

运行 npm run bundle -- /path/to/output，即可根据当前目录构建 .mcpb 桌面端捆绑包。安装时在本地输入凭据。此服务仍为只读。

更多 getmcpads 项目

Meta Ads · Google Ads · Google Analytics 4 · TikTok Ads · Pinterest Ads · X Ads

由 getmcpads 的 Emmanuel 维护。问题请联系：[email protected]。