mcp-gsc

mcp-gsc

Google Search Console MCP 服务 — 通过自然语言查询搜索分析数据、检查 URL、管理站点地图等。
使用 Bun + TypeScript 构建。适用于 Claude、Cursor 和任何 MCP 客户端。

---

快速开始

1. 获取凭据

你需要从 Google Cloud Console 获取 OAuth 客户端凭据。

1. 前往 Google Cloud Console

2. 创建项目（或选择现有项目）

3. 启用 Google Search Console API：

   • APIs & Services → Library → 搜索 "Google Search Console API" → Enable

4. 配置 OAuth consent screen（如果尚未配置）：

   • APIs & Services → OAuth consent screen → External
   • 填写应用名称和你的电子邮件，添加范围 https://www.googleapis.com/auth/webmasters

5. 创建凭据：

   • APIs & Services → Credentials → Create Credentials → OAuth client ID
   • 应用类型：Desktop app（自动允许 localhost 重定向）
   • 下载 JSON 文件

6. 设置凭据路径：

export GOOGLE_GSC_CREDENTIALS_PATH=/path/to/credentials.json

7. 运行设置以完成授权：

npx mcp-gsc setup

这会打开浏览器以进行 OAuth 授权，保存刷新令牌，验证对 GSC 资源的访问权限，并输出 MCP 客户端的配置片段。

2. 添加到 Claude Code

claude mcp add gsc --scope user --transport stdio \
  -e GOOGLE_GSC_CREDENTIALS_PATH=/path/to/credentials.json \
  -- npx -y mcp-gsc@latest

就是这样。重启 Claude Code 后即可使用这些工具。

如果你安装了 Bun，也可以使用 bunx mcp-gsc@latest。 通过 npx 运行时需要 Node 22+。

Claude Desktop / Cursor

将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "gsc": {
      "command": "npx",
      "args": ["-y", "mcp-gsc@latest"],
      "env": {
        "GOOGLE_GSC_CREDENTIALS_PATH": "/path/to/credentials.json"
      }
    }
  }
}

Codex CLI

添加到 ~/.codex/config.toml（TOML，而非 JSON）：

[mcp_servers.gsc]
command = "npx"
args = ["-y", "mcp-gsc@latest"]
startup_timeout_sec = 30
env = { GOOGLE_GSC_CREDENTIALS_PATH = "/path/to/credentials.json" }

Codex 的默认启动超时时间为 10s，对于首次执行 npx 获取包而言通常太短。请增大 startup_timeout_sec（30 足够），或全局安装软件包（npm i -g mcp-gsc），并改用 command = "mcp-gsc"。

服务账号（替代方案）

无需基于浏览器的 OAuth，即可进行服务端到服务端身份验证：

1. 在 Google Cloud Console 中创建服务账号
2. 下载 JSON 密钥文件
3. 在 Google Search Console 中，为每个资源将服务账号电子邮件地址添加为用户
4. 将 GOOGLE_GSC_CREDENTIALS_PATH 指向密钥文件 — 系统会自动检测身份验证类型

工具（25）

核心工具（始终可用）

站点

工具	描述
list_properties	列出所有 GSC 资源及其权限级别
get_property_details	查看资源的验证信息、所有权和权限

搜索分析

工具	描述
search_analytics	使用维度、筛选器和品牌细分查询搜索效果（点击次数、展示次数、CTR、排名）

维度：query、page、country、device、date、searchAppearance、hour

类型：web、image、video、news、discover、googleNews

注意：searchAppearance 不能与 query 或 page 组合使用。hour 需要设置 data_state="hourly_all"（仅限最近 10 天）。国家代码采用 ISO 3166-1 alpha-3 格式（usa、gbr、deu）。

站点地图

工具	描述
list_sitemaps	列出站点地图及其状态、类型、已编入索引的数量和错误
get_sitemap	查看站点地图详细信息和内容细分

URL 检查

工具	描述
inspect_url	查看 URL 编入索引状态、抓取信息、富媒体搜索结果和规范 URL
batch_inspect_urls	一次检查最多 10 个 URL，并按类别返回结果

速率限制：每个站点每分钟 600 次 + 每天 2,000 次（自动跟踪）。

导出

工具	描述
export_csv	将完整的搜索分析数据导出到本地 CSV 文件（每次调用自动分页处理 25K 行，最多 1M 行）

扩展工具（默认禁用）

设置 GOOGLE_GSC_ENABLE_EXTENDED_TOOLS=true 以启用：

报告套件

工具	描述
performance_overview	汇总指标和每日趋势细分
compare_periods	比较两个日期范围并计算差值
top_movers	两个时间段之间涨幅和跌幅最大的项目
device_country_breakdown	按设备和／或国家查看表现

SEO 套件

工具	描述
quick_wins	展现量高、点击率低且排名接近首页的查询（排名 4-20）
cannibalization	多个页面竞争同一查询
opportunity_finder	新兴查询、展现量增长但点击率低的查询，以及表现下滑的项目
position_tracking	特定查询／页面的排名变化趋势
ctr_anomalies	点击率相对于排名异常的查询
content_decay	展现量较历史峰值下降超过 50% 的页面／查询
weekly_seo_report	一站式报告：概览 + 快速见效项 + 涨幅最大的项目

技术 SEO 套件

工具	描述
indexing_coverage	批量检查 URL，并按类别显示索引状态
sitemap_health	站点地图错误模式、新鲜度，以及已索引与已提交数量之比

写入工具（默认禁用）

通过 GOOGLE_GSC_ENABLE_WRITES=true 启用：

工具	描述
add_site	在 GSC 中添加新网站
delete_site	从 GSC 中移除网站
submit_sitemap	提交新的站点地图
delete_sitemap	移除／撤销提交站点地图
request_indexing	通过 Indexing API 请求 Google 抓取 URL
get_indexing_status	查询 URL 上次提交索引的时间

Indexing API 的前置条件。 最后两个工具使用的 Google API 与此服务的其他工具不同，因此还需要满足其他工具不需要的三项条件：

1. 重新运行 mcp-gsc setup — 此功能推出前创建的凭据缺少 auth/indexing 范围。如果你的凭据缺少该范围，工具会明确提示。
2. 在 Google Cloud 项目中启用 Indexing API — console.cloud.google.com/apis/library/indexing.googleapis.com
3. 在 Search Console 中成为该资源的已验证 所有者。 完整用户权限并不足够。

Google 官方仅支持对带有 JobPosting 或 BroadcastEvent 结构化数据的页面使用 Indexing API，默认配额为每天 200 个 URL。该 API 会请求抓取，但绝不保证页面会被编入索引。

配置

变量	必需	默认值	描述
GOOGLE_GSC_CREDENTIALS_PATH	是	—	OAuth 客户端 JSON 文件或服务账号密钥的路径
GOOGLE_GSC_TOKEN_PATH	否	派生值	缓存的 OAuth 令牌路径（默认：凭据同目录下的 *_token.json）
GOOGLE_GSC_PROPERTY	否	—	默认资源网址（例如 sc-domain:example.com）。接受不带前缀的域名。
GOOGLE_GSC_ENABLE_WRITES	否	false	启用写入工具
GOOGLE_GSC_ENABLE_EXTENDED_TOOLS	否	false	启用扩展分析工具（额外 13 个）
GOOGLE_GSC_ENV_FILE	否	.env	.env 文件的路径
DEBUG	否	—	启用调试日志

资源解析： 你可以传入 example.com 这类不带前缀的域名，服务会根据你已验证的资源自动解析为 sc-domain:example.com 或 https://example.com/。

示例

向你的 AI 助手提出以下请求：

• “显示我本月排名前 10 的查询”
• “为 example.com 找出快速见效项”
• “过去 3 个月哪些页面的流量在下降？”
• “检查这些 URL 是否已编入索引：url1、url2、url3”
• “比较本周与上周的表现”
• “将过去 28 天的所有搜索分析数据导出为 CSV”
• “为我的网站生成每周 SEO 报告”
• “查找关键词自相竞争问题”

未来工具构想

• 内容差距分析（需要集成竞争对手数据）
• 集成 Core Web Vitals（通过 PageSpeed Insights API）
• 多资源对比
• 深入分析搜索外观
• 集成 Google Analytics 以获取转化数据
• 自动化报告计划

更新

使用 npx @latest（推荐）：始终获取最新版本。

使用二进制文件：服务会在启动时检查是否有新版本；如果版本过旧，会将提示记录到 stderr。

mcp-gsc --version

开发

需要 Bun。

git clone https://github.com/pijusz/mcp-gsc.git
cd mcp-gsc
bun install
bun test           # tests
bun run build      # standalone binary
bun run inspect    # MCP Inspector
bun run check      # biome format + lint

许可证

MIT