google-gsc

mcp-google-gsc

通过 Claude 使用 Google Search Console 的 MCP 服务——搜索分析、URL 检查和站点管理。

功能

• 搜索分析 —— 使用灵活的维度筛选条件（查询、页面、设备、国家/地区、日期）查询点击次数、展示次数、点击率和排名
• URL 检查 —— 检查任意 URL 的索引状态、移动设备易用性和富媒体搜索结果
• 站点列表 —— 列出已通过验证且经身份验证的账户（OAuth 用户或服务账户）可访问的所有 Search Console 资源
• 多客户端支持 —— 通过按目录映射配置来管理多个 GSC 资源

安装

从 npm 安装

npm install mcp-google-gsc

从源代码安装

git clone https://github.com/mharnett/mcp-search-console.git
cd mcp-google-gsc
npm install
npm run build

配置

安全提示： 切勿分享 .mcp.json 文件或将其提交到 git 中——它可能包含 API 凭据。请将 .mcp.json 添加到 .gitignore。

mcp-gsc 支持两种身份验证模式。请选择适合你设置的模式。两种模式都不需要将任何文件放在硬编码的本机路径中——凭据来自环境变量（或你创建的 config.json）。

应选择哪种模式：

• 服务账户（模式 B）——推荐用于无人值守、服务器或无头场景。 服务账户没有会过期或需要重新授权的交互式登录，因此适合始终在线的部署。唯一的设置要求是：必须在你想要查询的每个 Search Console 资源上授予服务账户邮箱访问权限（参见模式 B）。
• 用户 OAuth（模式 A）——适用于个人或交互式使用，即你想使用自己的 Google 账号进行授权。

同时配置两种模式时的优先级： 如果明确设置了服务账户密钥文件（GOOGLE_APPLICATION_CREDENTIALS，或 config.json 中的 credentials_file），则它的优先级高于任何 OAuth 刷新令牌或已存储的 OAuth 凭据。如果两者均未配置，服务会在启动时明确报错并显示引导信息，而不会静默猜测——服务没有本机默认路径，也不会在运行时静默切换身份验证模式。

模式 A：用户 OAuth（使用你自己的 Google 账号）

如果你想使用自己的 Google 登录账号（具有 Search Console 访问权限的账号）进行授权，请使用此模式。最适合个人或交互式使用。

1. 在 Google Cloud Console 中创建一个类型为桌面应用的 OAuth 2.0 客户端 ID，并启用 Search Console API。（对于桌面应用客户端，Google 接受任意 http://localhost 环回重定向——你无需预先注册端口。）
2. 导出客户端凭据：

   export GOOGLE_GSC_CLIENT_ID=...apps.googleusercontent.com
   export GOOGLE_GSC_CLIENT_SECRET=...
   

3. 生成刷新令牌（将打开浏览器，使用 PKCE 和 access_type=offline）：

   node get-refresh-token.cjs
   

   请勿将此命令的标准输出重定向到共享日志——此命令会按设计将刷新令牌打印到标准输出。

4. 将打印出的行复制到环境中：

   export GOOGLE_GSC_REFRESH_TOKEN=...
   

服务会在运行时从环境中读取 GOOGLE_GSC_CLIENT_ID、GOOGLE_GSC_CLIENT_SECRET 和 GOOGLE_GSC_REFRESH_TOKEN。

或者，运行引导式助手 npx mcp-gsc-auth。它会执行相同的 PKCE OAuth 流程，让你选择默认的 Search Console 资源，并将结果写入按用户保存的凭据文件。

模式 B：服务账户（推荐用于无人值守或服务器场景）

适用于服务器、无头或始终在线的环境——当没有人可以完成或刷新交互式登录时，推荐使用此方式。

1. 创建一个具有 Search Console API 访问权限的 Google Cloud 服务账户，并下载其 JSON 密钥文件。
2. 在你想要查询的每个 Search Console 资源上授予服务账户邮箱访问权限（在 Search Console 中将其添加为用户）。如果未在资源上授予此权限，服务账户虽然可以通过身份验证，但看不到任何站点。
3. 通过环境变量将密钥文件路径提供给服务（无需硬编码路径）：

   export GOOGLE_APPLICATION_CREDENTIALS=/path/to/your/service-account-key.json
   

OAuth 作用域

两种模式都只请求一个只读作用域：https://www.googleapis.com/auth/webmasters.readonly。这四个工具都只读取数据，不会写入任何内容，因此服务端不会请求读写权限。

该作用域在 config.json 的 oauth.scope 中定义一次（参见 config.example.json）。OAuth 助手和运行时读取同一个值，因此不会出现偏差。如果 config.json 不存在（例如全新安装），则会使用已提交的只读默认值。

多客户端配置（可选）

要将工作目录映射到 Search Console 属性，请在项目根目录中创建 config.json（参见 config.example.json）：

{
  "oauth": {
    "scope": "https://www.googleapis.com/auth/webmasters.readonly"
  },
  "clients": {
    "my-project": {
      "name": "My Project",
      "folder": "/path/to/project",
      "site_url": "https://example.com/"
    }
  }
}

用法

将以下内容添加到 Claude Code 的 .mcp.json 中：

{
  "mcpServers": {
    "gsc": {
      "command": "node",
      "args": ["/path/to/mcp-gsc/dist/index.js"]
    }
  }
}

或者，如果已全局安装：

{
  "mcpServers": {
    "gsc": {
      "command": "npx",
      "args": ["mcp-google-gsc"]
    }
  }
}

**Claude Desktop：**将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）。

工具

工具	描述
gsc_get_client_context	根据配置映射，从工作目录检测 GSC 属性
gsc_list_sites	列出已通过验证且已认证账号有权访问的所有 Search Console 属性
gsc_search_analytics	查询搜索效果数据（点击次数、展示次数、点击率、排名），支持维度和筛选条件
gsc_inspection	检查 URL 的索引状态、移动设备适用性和富媒体搜索结果

gsc_search_analytics

支持的维度：query、page、device、country、date。可使用 equals、contains、notContains 等运算符按任意维度筛选。日期范围默认为最近 28 天。

gsc_inspection

返回指定属性中某个 URL 的索引覆盖率、抓取状态、移动设备适用性判定和富媒体搜索结果详情。

架构

• 弹性——使用 cockatiel 对所有 Google API 调用进行重试，并采用指数退避和断路器模式
• 日志记录——通过 pino 实现结构化日志记录，并支持配置日志级别
• 响应处理——将响应截断至 200KB，以符合 MCP 传输限制

许可证

MIT ——参见 LICENSE。

---

由 Mark Harnett / drak-marketing 构建