Google Search Console Connector

适用于 Claude Code 的 Google Search Console 连接器

通过 Claude Code、Google Antigravity 或任何 MCP 客户端，将任意网站项目连接到 Google Search Console。使用 Google 账号登录一次，即可询问 Claude 有关点击次数、查询、排名和索引的问题；只需一个命令，即可将所有 GSC 报告导出为 CSV，并在本地 SEO 仪表板中跟踪所有数据。

这是一个开源的 Search Console MCP 服务、GSC 报告导出工具和仪表板，完全在你的电脑上运行。无需配置 Google Cloud，也无需 API 密钥：只需使用 Google 账号登录。

如果你觉得它有用，请在 GitHub 上点个 ⭐，帮助更多人发现它。

文档和更新： claude-repo.com/google-search-console-connector

---

为什么要开发它

如果你使用 AI 编码 Agent 构建网站，要让它获取 Search Console 数据，通常得登录 search.google.com，点击“导出”，下载 CSV，再把文件拖进聊天窗口。每个网站都得重复这一套流程。

这个工具省去了这些步骤：

npx google-search-console-connector report

这个命令会下载与 Search Console“导出”按钮相同的报告（日期、查询、网页、国家/地区、设备、搜索外观），还会下载与上一时段的对比数据、查询与网页的对应关系、站点地图，以及一份供 Claude 阅读的 summary.md。在 Claude Code 中，你甚至不需要输入命令。只需说“获取 Search Console 报告”，Claude 就会运行 gsc_export_report 工具。

功能

• 使用 Google 账号登录。 在浏览器中点击一次即可，使用 Google 自有的 OAuth 2.0（PKCE）。无需 Google Cloud 项目、API 密钥或密码。
• 一键导出 GSC 报告。 为一个网站或所有网站（--all-sites）获取 CSV、JSON 和 Markdown 报告，支持最长 16 个月的任意时间范围。
• 适用于 Claude Code 和 Antigravity 的 MCP 服务。 提供 18 个工具：性能数据、小时级数据、品牌与非品牌查询、URL 检查、站点地图、添加资源和验证所有权。
• 本地 SEO 仪表板。 显示与上一时段对比的关键指标、趋势图（按小时、天、周、月）、查询、网页、国家/地区、设备、站点地图和 URL 检查结果。提供浅色和深色主题。
• 机会。 找出排名有望提升的关键词（排名第 4–20 位）、点击率较低的首页网页，以及点击次数正在减少的查询。
• 品牌与非品牌对比。 只需设置一次品牌词，仪表板、报告和 Claude 都能据此拆分流量。
• 图表备注。 Claude 可以在发布 SEO 修改时为图表添加标记（“重写了服务页面标题”），方便你查看哪些修改影响了数据。
• 网站验证。 Claude 可以在 Search Console 中添加新网站、将验证元标记写入代码，并在你部署后验证网站。
• 保持与 Google 同步。 支持最新的 Search Console API 功能，包括小时级数据、Discover 和 Google 新闻。每周检查会提示新增的 API 字段和 Search Central 公告。
• 默认保护隐私。 令牌和 Search Console 数据只保存在你的设备上，且仅发送给 Google。中间没有其他服务器。

快速开始

你需要 Node.js 20 或更高版本，以及一个有权访问 Search Console 的 Google 账号。

1. 将其添加到 Claude Code（添加一次，适用于所有项目）：

claude mcp add gsc --scope user -- npx -y google-search-console-connector@latest

在 Windows 上，使用 cmd /c 包装 npx：

claude mcp add gsc --scope user -- cmd /c npx -y google-search-console-connector@latest

如果想直接从 GitHub 运行最新代码，而不是使用 npm，请用 npx -y github:malaysherasia-ai/google-search-console-connector-for-claude-code 替换 npx -y google-search-console-connector@latest。首次启动时需要构建，大约耗时 20 秒。GitHub 构建不包含一键登录客户端，因此你需要使用自己的 Google Cloud OAuth 客户端（Connect 页面会指导你完成设置）。

2. 连接网站项目。 在网站文件夹中打开 Claude Code，然后输入：

将此项目连接到 Google Search Console

Claude 会调用 gsc_connect，在浏览器中打开一个页面：

1. 一次性询问是否允许收集匿名使用指标（由你选择是或否），
2. 使用有权访问 Search Console 的账号通过 Google 登录。在 Google 显示的第二个屏幕上，点击“查看和管理您已验证网站的 Search Console 数据”旁边的复选框，然后再点击“继续”；Google 默认不会勾选此框，
3. 选择属于此项目的 Search Console 资源。

Google 显示的内容（账号详情已隐藏）：

就这么简单。Google 已验证此应用的品牌信息，而且应用只请求非敏感权限，因此无需点击任何“未经验证的应用”屏幕。如果继续时没有勾选该复选框，连接器会保留你之前的登录状态，并提示你重试。

3. 尽管提问：

网站在过去 28 天的表现如何？ 我们在哪些查询中排名第 4–20 位？哪些页面需要改进？ 拉取过去 3 个月的 GSC 报告。 检查 https://example.com/services/，告诉我它为什么未被编入索引。 提交站点地图，然后添加一条图表注释，说明我们推出了新的地点页面。 打开 Search Console 控制面板。

你也可以在终端中运行所有操作：

npx google-search-console-connector connect     # browser setup and sign-in
npx google-search-console-connector report      # export reports to .gsc-reports/
npx google-search-console-connector dashboard   # open the local dashboard
npx google-search-console-connector demo        # try the dashboard with sample data

与 Google Antigravity、Cursor 和其他 MCP 客户端搭配使用

任何能够启动本地（stdio）服务的 MCP 客户端都可以使用。将以下内容添加到其 MCP 配置中（在 Antigravity 中，打开 MCP 服务设置并编辑原始配置）：

{
  "mcpServers": {
    "google-search-console": {
      "command": "npx",
      "args": ["-y", "google-search-console-connector@latest"]
    }
  }
}

服务会将其启动所在的文件夹用作项目目录。如果你的客户端在其他位置启动服务，请设置 "env": { "GSC_PROJECT_DIR": "/path/to/your/site" }。

进阶：使用自己的 Google Cloud 项目

大多数人可以跳过此步骤。希望通过自己的 Google Cloud 项目（使用自己的配额和同意屏幕）进行登录的代理机构和开发者，可以在登录页面选择 Use my own Google Cloud project。步骤如下：

1. 创建 Google Cloud 项目，或选择现有项目。
2. 启用 Google Search Console API。
3. 启用 Site Verification API（用于验证新网站）。
4. 配置同意屏幕：选择 External，并将你的邮箱添加为测试用户。然后将应用发布为 In production。仍处于“Testing”状态的应用，其登录有效期每 7 天就会过期。个人使用无需通过 Google 的应用验证；Google 会显示“未验证的应用”提示，你可以选择 Advanced → Go to (your app) 继续。
5. 创建 OAuth 客户端 ID，类型选择 Desktop app，下载 JSON 文件，然后将其放到 Connect 页面。

这两个 API 都是免费的。使用自己的客户端意味着配额和同意屏幕都由你掌控。要切回内置登录方式，请使用该页面顶部的链接，或前往控制面板中的 Settings。

一条命令生成 Search Console 报告

npx google-search-console-connector report [--days 28] [--type web] [--site URL] [--all-sites] [--out DIR]

文件	内容
summary.md	与上一周期相比的总计、品牌词细分、热门查询和页面、涨幅最大和跌幅最大的项目、排名接近首页的关键词以及点击率较低的页面
Dates.csv、Queries.csv、Pages.csv、Countries.csv、Devices.csv、Search appearance.csv	列与 Search Console 的导出内容相同，另含上一周期的列
Query-page pairs.csv	哪个页面针对哪个查询获得排名（Search Console 界面无法导出此内容）
Sitemaps.csv	已提交的网站地图、状态、错误和警告
Filters.csv、report.json	实际请求的内容，以及所有 JSON 格式的数据

报告会保存到项目中的 .gsc-reports/<site>/<date>_last-<n>-days/，并将 .gsc-reports/ 添加到 .gitignore，以免搜索数据进入提交内容或部署的网站。超过 Google 的 25,000 行限制时，会自动分页获取数据。

MCP 工具

工具	功能
gsc_connect	打开浏览器 Connect 流程并等待其完成
gsc_status / gsc_disconnect	查看连接状态；撤销访问权限
gsc_list_sites / gsc_link_project	列出资源；设置此项目的默认资源
gsc_performance_summary	与上一周期相比的总计，以及热门查询和页面
gsc_search_analytics	任意 Search Analytics 查询：包含 hour 在内的维度、筛选条件（正则表达式）、搜索类型、品牌词/非品牌词
gsc_export_report	一条命令导出报告，可针对一个或所有网站
gsc_inspect_url	URL 检查：索引状态、上次抓取时间、规范网址、富媒体搜索结果
gsc_list_sitemaps / gsc_submit_sitemap / gsc_delete_sitemap	管理网站地图
gsc_add_site / gsc_get_verification_token / gsc_verify_site	添加资源并验证所有权（通过元标签、HTML 文件或 DNS）
gsc_set_brand_terms	用于将查询标记为“品牌词”的词语
gsc_add_annotation	在效果图表中添加带日期的注释
gsc_open_dashboard	打开本地控制面板

仪表板

运行 npx google-search-console-connector dashboard，或让 Claude 打开它。它仅在 127.0.0.1 上运行，并通过一次性链接打开。

• **概览：**点击次数、展示次数、点击率和排名与上一时段的对比，以及覆盖最近 24 小时（按小时）至 16 个月的趋势图，可按日、周或月分组
• **查询和页面：**可排序、搜索、更改列，以及导出 CSV
• **机会：**临近首页的关键词、点击率低的页面、排名下降的查询
• **站点地图和检查：**提交站点地图、检查其状态、检查任意 URL
• **设置：**账号、项目资源、品牌词、图表注释、使用情况指标选项

无需 Google 账号即可试用：npx google-search-console-connector demo。

Google API 提供和不提供的内容

Search Console 不断添加功能。其中一些会提供给 API，另一些则仅保留在网页界面中。此表反映了截至 2026 年 10 月的 Google API 情况。

Search Console 功能	此处是否支持	备注
效果：按日期、查询、页面、国家/地区、设备、搜索外观划分的点击次数、展示次数、点击率、排名	是
每小时数据（最近约 10 天）	是	hour 维度，仪表板中的“24h”范围
Discover 和 Google News 效果	是	Google 不会报告这些内容的查询或排名
品牌词与非品牌词查询	是	根据你的品牌词和 RE2 正则表达式筛选器生成
按周和按月查看	是	根据每日数据分组
图表注释	是，本地支持	存储在 .gsc-connect.json 中；Google 自带的注释不在 API 中
AI Overviews 和 AI Mode	包含在 Web 总计中	Google API 无法将它们单独区分
生成式 AI 效果报告、Web 多模态搜索类型、社交平台资源、查询组	暂不支持	目前在 Search Console 中仅能通过网页界面使用。Google 将这些功能加入 API 后，更新检查会立即提示

隐私和匿名使用情况指标

• 你的 Search Console 数据绝不会离开你的计算机，除非是在你与 Google 之间传输。
• 令牌存储在 ~/.gsc-connect/ 中，文件权限仅限所有者访问。在 Google 处断开连接会撤销这些令牌。
• 项目设置（.gsc-connect.json：资源、品牌词、图表注释）不含机密信息，可以安全提交。
• **匿名使用情况指标由你选择是否启用。**首次使用时会询问一次。如果你选择否，则永远不会发送任何内容。如果你选择是，应用会通过 Measurement Protocol 向 Google Analytics 4 发送事件名称（例如 view_changed 或 mcp_tool_called）、应用版本、操作系统和随机安装 ID。绝不会发送网站 URL、页面 URL、查询、指标或你的账号信息。浏览器中不会运行跟踪脚本，也不会设置 Cookie。设置 →“已发送的内容”会逐项显示发送的事件原文，你可以随时在此更改选择。设置 DO_NOT_TRACK=1 或 GSC_CONNECT_TELEMETRY=0 可永久关闭此功能。完整事件列表见 src/telemetry.ts。
• **更新检查：**应用每天会向公共 npm registry 查询最新版本号。设置 GSC_CONNECT_UPDATE_CHECK=0 可关闭此功能。

安全

• 本地服务仅监听 127.0.0.1，会检查 Host 标头，并要求提供通过一次性启动链接设置的会话 Cookie。
• OAuth 使用带 PKCE（S256）的环回重定向，并检查 state，这符合 Google 对桌面应用的建议。
• 登录时请求：webmasters（Search Console）和 openid email（用于显示已连接的账号）。仅在首次验证新网站时，才会单独请求 siteverification。

请私下报告漏洞；详情请参阅 SECURITY.md。

配置

变量	用途
GSC_PROJECT_DIR	如果 MCP 客户端从其他位置启动服务，则用于指定项目文件夹
GSC_CLIENT_ID、GSC_CLIENT_SECRET	使用环境变量中的自有 OAuth 客户端，而非内置登录
GSC_CONNECT_HOME	凭据的存储位置（默认为 ~/.gsc-connect）
GSC_CONNECT_PORT	首选本地端口（默认为 4817；若被占用则使用任意可用端口）
GSC_CONNECT_TELEMETRY=0、DO_NOT_TRACK=1	永不发送使用情况指标
GSC_CONNECT_UPDATE_CHECK=0	不检查 npm 是否有新版本

常见问题

Google Search Console API 是免费的吗？ 是。Google 不会对 Search Console API 或 Site Verification API 收费，而且此工具没有任何付费部分。

我需要 Google Cloud 账号吗？ 不需要。使用你已有的 Search Console Google 账号登录即可。自有 Google Cloud 项目是可选的高级设置。

谁能看到我的数据？ 只有你和 Google。登录授权的是你的计算机，而不是某个服务：令牌存储在 ~/.gsc-connect/ 中，报告保存在项目文件夹里。请参阅隐私政策。

我能导出超过 1,000 行吗？ 可以。Search Console 网页版导出最多只显示 1,000 行。API 每次请求最多返回 25,000 行，此工具会持续翻页，最多可达到 Google 对每种搜索类型规定的每日 50,000 行上限。

它支持网域资源（sc-domain:）吗？ 支持。网域资源和网址前缀资源都可以使用。网域资源通过 DNS 验证。

它能支持多个网站吗？ 可以。每个项目文件夹都会关联自己的资源，report --all-sites 会导出你有权访问的所有资源。

如何更新？ 如果你使用 @latest 安装，请重启 Claude Code。仪表板和 CLI 会在有新版本时告知你。

开发

git clone https://github.com/malaysherasia-ai/google-search-console-connector-for-claude-code.git
cd google-search-console-connector-for-claude-code
npm install
npm run build
npm run demo                                  # dashboard with sample data
claude mcp add gsc-dev -- node "$PWD/dist/index.js"
npm run check:google                          # what has Google changed since the last release?

有关如何根据 Google 的变更和使用情况规划版本发布，请参阅 RELEASING.md；有关如何参与贡献，请参阅 CONTRIBUTING.md。

许可证

MIT。与 Google 无关，也未获 Google 认可。Google Search Console 是 Google LLC 的商标。