mcp-google-gsc

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

功能

• 搜索分析 —— 使用灵活的维度过滤器（查询、页面、设备、国家、日期）查询点击量、展示次数、点击率和排名

• URL 检查 —— 检查任何 URL 的索引状态、移动设备可用性和富媒体搜索结果

• 站点列表 —— 列出通过你的认证账户（OAuth 用户或服务账户）可访问的所有已验证的 Search Console 资源

• 多客户端支持 —— 通过按目录配置映射管理多个 GSC 资源

Related MCP server: Google Search Console MCP Server

安装

从 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_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 构建