Google Search Console

Google Search Console MCP 服务

一个本地模型上下文协议服务，可将 AI 助手（Claude Code、Claude Desktop、Cursor 及任何其他 MCP 客户端）连接到 Google Search Console API。用自然语言询问点击、查询、网页、索引和站点地图；服务会将问题转化为正确的 API 调用，并返回结构化数据。

服务在你的机器上运行并与 Google 通信；它读取的唯一其他网站是你自己的网站，且仅在进行索引审核时读取。它只存储你的登录信息和审核进度，不存储其他内容。

非官方。 本项目与 Google 无关，也未获其认可。你需要使用自己的 Google Cloud 凭据，并负责遵守 Google 的条款使用本项目。

为什么选择它

• 捕获 API 的陷阱。 对许多错误请求，Google 返回的不是错误，而是空结果：无效的正则表达式、两位数国家代码、超过 10 天的小时数据、未来的日期范围。其他一些参数组合则会返回简短的 400 错误。服务会在调用前逐一检查这些情况，并用浅显的语言解释原因。这些规则经过在线 API 验证，而非照搬博客文章。
• 解释变化，而不只是提供数字。 explain_change 会按网页、查询、国家/地区、设备和搜索展示形式拆分涨跌，区分展示次数减少与点击率下降，并将变化与 Google 发布的更新对应起来。
• 全面的索引审核。 Google 的 API 不会公开“网页索引”报告中的 URL 列表，因此 audit_indexing 会重新构建这些列表：在每日配额内检查站点地图中的每个 URL，次日从上次停止的位置继续，还能将每个在线网页与 Google 上次看到的内容进行比对。
• 具备防护措施，覆盖 API 的全部功能。 读取和写入功能均已启用：可以添加和移除站点资源，以及提交和移除站点地图。进行更改时必须提供站点资源的准确名称；执行这些操作的工具会标记为写入操作（删除则标记为破坏性操作），客户端可以据此在执行前询问是否确认。将 GSC_ENABLE_WRITES=0 设为关闭写入功能。
• 结构化输出。 每个工具都声明了输出架构，返回的数据行采用带名称的字段，且每个分析结果都包含发送给 Google 的确切请求。
• 完整的 API 覆盖范围：搜索分析（所有搜索类型、筛选器、数据状态和分页）、小时数据、搜索展示形式、URL 检查（单个和并发批量）、站点地图和站点资源；此外还为每种搜索类型（Discover、Images、视频、Google 新闻、“新闻”标签页）提供专用工具，只接受该类型支持的内容。
• 基于当前技术栈构建：采用 MCP Python SDK 2.x（兼容 2026-07-28 协议和更早版本的客户端）及异步客户端，因此批量检查会并发运行。

快速开始

你需要安装 uv，并拥有一个至少可访问一个 Search Console 资源的 Google 账号。

1. 创建 OAuth 客户端（在 Google Cloud 中操作，约需五分钟，只需一次）：

   1. 打开 console.cloud.google.com，创建或选择一个项目。
   2. APIs & Services > Library：启用 Google Search Console API。
   3. Google Auth Platform > Branding：填写应用名称和你的邮箱。
   4. Google Auth Platform > Audience：选择 External，将你的 Google 账号添加为测试用户，然后点击 Publish app，使状态变为 In production。 跳过此步骤，Google 会每 7 天让你的登录失效。
   5. Google Auth Platform > Clients > Create client：选择 Desktop app。下载 JSON 文件，并将其保存在任何代码仓库之外，例如 ~/.config/open-gsc-mcp/client_secret.json。

2. 登录（会打开一次浏览器；服务本身不会打开浏览器）：

   uvx open-gsc-mcp@latest auth login --client-file ~/.config/open-gsc-mcp/client_secret.json
   

   Google 会显示“Google 尚未验证此应用”，因为这是你自己的应用，且尚未经过审核；请选择 Advanced > Go to (your app)。完成后，命令会列出它能访问的资源。

3. 将服务添加到客户端（见下文），重启客户端，然后询问类似 “本月 example.com 上哪些查询的点击量下降最多？”

客户端配置

Claude Code

claude mcp add --scope user gsc -- uvx open-gsc-mcp@latest

Claude Desktop：编辑 claude_desktop_config.json （macOS：~/Library/Application Support/Claude/，Windows：%APPDATA%\Claude\）：

{
  "mcpServers": {
    "gsc": {
      "command": "uvx",
      "args": ["open-gsc-mcp@latest"]
    }
  }
}

如果 Claude Desktop 报告找不到 uvx，请使用其绝对路径 （macOS 和 Linux 上运行 which uvx，Windows 上运行 where uvx）。

Cursor：将相同的 mcpServers 配置块添加到 ~/.cursor/mcp.json。

@latest 会让 uvx 在每次客户端启动服务时检查是否有新版本。 不加它时，uvx 会一直运行首次缓存的版本。若要仅在你选择时升级，请改为指定版本，例如 [email protected]。

要传递设置，请在服务条目中添加 env 对象，或在 claude mcp add 后添加 -e NAME=value。路径必须是绝对路径：客户端会从任意工作目录启动服务。

服务账号（无头模式）

对于服务器、CI 或共享机器，请使用服务账号，而非个人登录账号：

1. 在 Google Cloud 中，前往 IAM & Admin > Service Accounts：创建服务账号，然后选择 Keys > Add key > JSON。（某些组织会通过政策禁止创建密钥。）

2. 在 Search Console 中，前往 Settings > Users and permissions > Add user：将服务账号的邮箱添加到每个资源，并授予“完全”或“受限”权限。

3. 将服务指向密钥：

   claude mcp add --scope user gsc -e GSC_SERVICE_ACCOUNT_FILE=/abs/path/key.json -- uvx open-gsc-mcp@latest
   

设置 GSC_SERVICE_ACCOUNT_FILE 后，它的优先级高于任何 OAuth 登录。

工具

工具	功能
list_sites	此账号可访问的资源，包含准确的 site_url 和权限级别。
get_site	单个资源的类型和权限级别。
query_search_analytics	按查询、页面、国家/地区、设备、日期或搜索外观统计点击次数、展示次数、点击率和排名；支持任意搜索类型、筛选条件、final 或 all 数据以及分页。
query_hourly_analytics	按小时提供相同的数据，涵盖最近约 10 天。报告不完整小时的起始时间。
query_discover_analytics	按页面、国家/地区或日期统计 Google Discover 数据。不提供查询、设备或排名，因此该工具不支持这些维度。
query_image_analytics	Google 图片：图片搜索结果中的查询、页面和排名。
query_video_analytics	Google 搜索的“视频”标签页。
query_google_news_analytics	按页面、国家/地区、设备或日期统计 Google 新闻（news.google.com 和应用）数据。不提供查询或排名。
query_news_tab_analytics	Google 搜索的“新闻”标签页，包含查询和排名。
list_search_appearances	此资源获得的富媒体搜索结果及其他搜索结果功能：两步外观查询中的第一步。
query_search_appearance	第二步：按查询、页面、国家/地区、设备或日期细分一种搜索外观。
compare_periods	对比两个等长时间段：总计和各项变化，包括绝对值和百分比，按变化幅度从大到小排列。
explain_change	解释两个时间段之间流量变化的原因：哪些页面、查询、国家/地区、设备和搜索外观导致了变化，展示次数和点击率各贡献多少，以及这些时间段内或附近发布的 Google 更新。
inspect_url	检查单个 URL 的索引状态、覆盖范围、规范网址（Google 认定的与您设置的）、抓取情况、robots.txt 和富媒体搜索结果。
batch_inspect_urls	并发检查最多 50 个 URL，提供进度、每个 URL 的错误和判定摘要。配额用尽时会平稳停止。
audit_indexing	检查站点地图中的所有 URL，按需分多次调用、历经多天完成，并按索引状态分组，提供可能的修复建议；还会检查规范网址冲突、有展示次数但未获得展示的已索引页面，以及未列入站点地图的页面；可选择实时检查每个页面。
list_sitemaps、get_sitemap	已提交的站点地图，包括错误、警告、待处理状态和 URL 数量。

1.1.0 中的 query_news_analytics 已弃用：调用仍可使用，并会转到由其 source 选择的新新闻工具，直到它在 2.0.0 中移除。

有四个工具会进行更改：submit_sitemap、delete_sitemap、add_site 和 delete_site。 它们只接受资源的准确 site_url，且站点地图必须属于该资源。 这些工具标记为写入操作（删除操作标记为破坏性操作），并会指示模型先向您确认，但服务本身不会主动询问您：您是否会看到提示，取决于客户端的权限设置。这四个工具涵盖了 Google API 允许的所有更改：它无法请求编入索引、从搜索中移除 URL，也无法管理用户和设置。若要运行不包含这些工具的服务，请设置 GSC_ENABLE_WRITES=0。

站点可指定为 sc-domain:example.com、https://www.example.com/、裸域名 example.com，或该站点上的任意 URL。除准确的资源外，其他值都会根据您的实际资源列表解析到包含该值的资源；结果会说明这一点。如果传入的是页面 URL，结果还会注明数据涵盖整个资源。

提示词：weekly_report、indexing_audit 和 content_opportunities 是现成的工作流，包含具体日期和准确的工具调用。

索引审核会在本地保存进度，因此每次调用 audit_indexing 都会从上次停止的位置继续。每次检查需要几秒钟，因此一次调用约可处理 50 个 URL；对于大型站点，请在终端中运行 uvx open-gsc-mcp@latest audit sc-domain:example.com（或通过 cron 每日运行），以用足每天 2,000 个 URL 的额度，然后向助手询问结果。

配置

变量	默认值	用途
GSC_SERVICE_ACCOUNT_FILE	未设置	服务账号密钥；设置后将替代 OAuth。
GSC_OAUTH_CLIENT_FILE	未设置	OAuth 客户端 JSON，因此 auth login 无需 --client-file。
GSC_TOKEN_FILE	每用户配置目录	auth login 保存登录信息的位置（权限模式为 0600）。
GSC_ENABLE_WRITES	1	设置为 0 可移除 4 个会进行更改的工具；此时 auth login 只会请求读取权限。
GSC_LOG_LEVEL	INFO	DEBUG 还会记录每个 HTTP 请求。日志输出到 stderr。
GSC_DATA_DIR	每用户数据目录	索引审计在此保存进度（单个 SQLite 文件，仅所有者可访问）。

命令行：

uvx open-gsc-mcp@latest              # run the MCP server over stdio (what clients do)
uvx open-gsc-mcp@latest auth login   # sign in; --read-only to grant reads only, --no-browser over SSH
uvx open-gsc-mcp@latest auth status  # which credentials are used, and do they work
uvx open-gsc-mcp@latest auth logout  # revoke and delete the saved login
uvx open-gsc-mcp@latest audit SITE   # inspect up to a day's 2,000 sitemap URLs; --fetch-pages

为你处理的 API 行为

Google 的行为	服务的处理方式
searchAppearance 不能与任何其他维度分组（400）。	拒绝请求，并提示使用两步模式。
对 searchAppearance 使用 notEquals/notContains 会返回你原本想排除的行（已确认是 Google 的错误）。	拒绝请求并说明原因。
Discover 和 Google News 没有查询数据（400）和排名位置；Discover 没有设备数据（400）。	拒绝 query（以及 Discover 的 device）；从行中排除排名位置。表层工具根本不会提供这些选项。
searchAppearance 筛选条件必须是对应搜索类型的精确大写外观名称（其他值均为 400）。	要求使用 equals，将名称转为大写，并提供专用的第二步工具。
hour 需要 dataState=hourly_all，且不能与 date 组合（400）。	专用的每小时工具会同时设置这两项。
大约 10 天以前的每小时数据、未来日期范围、无效或非 RE2 正则表达式、两字母国家代码或未知设备都会返回零行且不报错。	在调用前拒绝上述每种情况，以及任何晚于今天的结束日期；这通常是日期错误。
日期采用太平洋时间；历史数据跨度为 16 个月。	使用太平洋时间；将开始日期限制在范围内并说明原因。
byProperty 聚合在按页面分组或使用筛选条件时，以及针对 Discover 和 Google News 时会失败（400）。	拒绝请求。
最新数据并不完整，但 Google 只会在按日期分组时说明数据从何时开始不完整。	报告 first_incomplete_date / first_incomplete_hour，并注明其他分组可能包含最近约 3 天的数据；比较默认使用 final 数据。
每次请求最多返回 25,000 行，且仅返回靠前的行。	默认返回 100 行，并提供 next_start_row 用于分页。
URL Inspection：每个资源每天 2,000 次、每分钟 600 次。	批次每次处理 5 个；遇到配额错误时会正常停止。
siteUrl 必须与资源字符串完全一致。	将裸域名和 URL 解析到包含它们的资源。
页面索引报告中的 URL 列表不在 API 中，且 URL Inspection 每天最多调用 2,000 次。	audit_indexing 会根据你的站点地图重建列表，所需时间可能跨越多天。

Google 的 API 不提供以下功能，因此任何服务都无法提供：生成式 AI 报告（AI Overviews 和 AI Mode）、平台资源（Instagram、TikTok、X、YouTube）、品牌查询筛选条件、Core Web Vitals、人工处置和链接。

故障排查

• “您的 Google 登录已过期或被撤销（invalid_grant）”：OAuth 应用可能仍处于 Testing 状态，登录有效期因此被限制为 7 天。发布该应用（Quick start，第 1.4 步），然后再次运行 auth login。
• “未登录”：运行 uvx open-gsc-mcp@latest auth login --client-file ...，或设置 GSC_SERVICE_ACCOUNT_FILE。
• 没有资源，或服务账号收到 403 错误：在 Search Console 中，将服务账号的电子邮件地址添加为该资源的用户。更改设置还需要拥有该资源的 Owner 或 Full 权限。
• “您的 Google 登录仅允许读取”：您是在完全访问权限成为默认设置之前登录的，或者使用了 --read-only。再次运行 auth login 以允许更改。
• 结果为空：检查日期范围（太平洋时间；final 数据会延迟 2–3 天）、search_type 和筛选条件。每个结果中的 notes 和 request 会显示请求内容。
• 端到端检查设置：uvx open-gsc-mcp@latest auth status。

安全与隐私

• 通过 stdio 在本地运行，不收集遥测数据。它会调用 Google API，并读取 Google 的公开更新源（status.search.google.com）以执行 explain_change。
• 索引审计还会读取您资源的站点地图，以及在使用 fetch_pages 时读取该资源的页面。它只会获取资源内的 URL，不会访问解析到私有或本地地址的主机，并且仅在重定向仍位于该资源内时才会跟随重定向。对于每个页面，它只保留状态代码、重定向、robots 指令和规范 URL。
• 审计进度（URL 及其索引状态）保存在您用户数据目录（GSC_DATA_DIR）中的单个 SQLite 文件里，仅您可读取。
• OAuth 登录信息存储在您的用户配置目录中，并设置为仅所有者可访问的权限。auth logout 会在 Google 撤销登录信息并将其删除。
• 登录时会向 Google 请求完整的 Search Console 访问权限，写入工具需要此权限。使用 auth login --read-only（或 GSC_ENABLE_WRITES=0）仅授予读取权限。
• 查询和页面字符串来自搜索者和其他网站。服务会指示模型将它们视为数据，而非指令。

如需私下报告漏洞，请参阅 SECURITY.md。

开发

git clone https://github.com/onlymoein/google-search-console-mcp
cd google-search-console-mcp
uv sync
uv run pytest                # unit and in-memory MCP tests, no network
uv run ruff check . && uv run ruff format --check . && uv run pyright

针对您自己的资源进行实时只读检查：

export GSC_SERVICE_ACCOUNT_FILE=/abs/path/key.json
GSC_TEST_SITE=sc-domain:example.com uv run pytest -m live
uv run python scripts/probe_compat.py sc-domain:example.com

请参阅 CONTRIBUTING.md，了解项目布局以及如何添加工具。

许可证

MIT