Google Search Console Mcp Server

Google Search Console MCP 服务

一个模型上下文协议（MCP）服务，可通过 Claude Code 和 Cursor 以编程方式访问 Google Search Console API 数据。

快速开始

初次使用此 MCP 服务？ 请跳转到分步设置指南查看完整说明。

功能

• 🔍 列出网站 - 获取你有权访问的所有 Search Console 资源
• 📊 搜索分析 - 通过灵活的筛选条件查询搜索效果数据
• 🗺️ 站点地图信息 - 获取站点地图状态和索引统计信息
• 🔎 网址检查 - 检查特定网址的详细索引状态
• 📤 提交网址以供索引 - 请求 Google 为网址编制索引或将其移除
• 📈 比较时间段 - 比较两个时间段内的搜索效果
• 🛡️ 健壮的错误处理 - 提供详细的错误消息和可操作的指导
• 🔄 自动重试逻辑 - 处理速率限制和暂时性故障
• ✅ 输入验证 - 在调用 API 前验证所有参数

前提条件

使用此 MCP 服务之前，你需要：

1. Google Search Console

• 已在 Search Console 中注册网站
• 已验证网站所有权
• 拥有对你想查询的 Search Console 资源的访问权限

2. Google Cloud Platform (GCP)

• 一个 GCP 项目（免费层级即可满足需求）
• 已启用 Google Search Console API
• OAuth 2.0 客户端 ID 凭据（桌面应用类型）
• （可选）如果要使用 submit_url_for_indexing，需启用 Indexing API

💡 注意：你只需设置一次 GCP。CLIENT_ID 和 CLIENT_SECRET 可在 Search Console 中的多个网站间重复使用。

设置

1. 配置 Claude Code

在项目根目录中创建 .mcp.json：

{
  "mcpServers": {
    "google-search-console": {
      "command": "npx",
      "args": ["-y", "-p", "google-search-console-mcp-server", "google-search-console-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret",
        "GOOGLE_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

⚠️ 重要：args 必须包含以下三个部分：

1. "-y" - 自动确认 npx 提示
2. "-p", "google-search-console-mcp-server" - 包名称
3. "google-search-console-mcp" - 可执行文件名称（与包名称不同！）

💡 注意：GOOGLE_REDIRECT_URI 默认值为 http://localhost:8080，除非你想使用其他端口，否则无需指定。

2. 获取 Google OAuth 凭据

💡 提示：你可以使用其他服务（Supabase、Firebase 等）中的现有 OAuth 2.0 客户端 ID，也可以新建一个。

1. 前往 Google Cloud Console
2. 创建或选择项目
3. 启用 API：
   • 前往“APIs & Services” → “Enable APIs and Services”
   • 搜索并启用 “Google Search Console API”
   • （可选）如果要使用 submit_url_for_indexing，请启用 “Indexing API”
4. 创建或使用现有 OAuth 2.0 客户端 ID：
   • 前往“APIs & Services” → “Credentials”
   • 选项 A：使用现有 OAuth 2.0 客户端（跳到第 5 步）
   • 选项 B：创建新的 → “OAuth 2.0 Client ID” → 应用类型：桌面应用
5. 配置已获授权的重定向 URI：
   • 点击 OAuth 2.0 客户端 ID
   • 在“Authorized redirect URIs”下，点击“Add URI”
   • 添加：http://localhost:8080（末尾不要加斜杠！）
   • 点击“Save”
6. ⚠️ 重要：添加测试用户（如果 OAuth 同意屏幕处于测试模式）：
   • 前往“OAuth consent screen”
   • 查看“Publishing status” - 如果显示 “Testing”：
   • 滚动到“Test users”部分
   • 点击“+ ADD USERS”
   • 添加你的 Google 账号邮箱（用于身份验证的账号）
   • 点击“Save”
   • 如果不执行此步骤，你会收到 access_denied 错误！

💾 保存凭据：复制 CLIENT_ID 和 CLIENT_SECRET。你将在下一步中用到它们。

3. 获取刷新令牌

运行交互式设置命令：

npx -y -p google-search-console-mcp-server google-search-console-mcp-setup

系统会提示你输入：

• GOOGLE_CLIENT_ID（来自第 2 步）
• GOOGLE_CLIENT_SECRET（来自第 2 步）
• GOOGLE_REDIRECT_URI（按 Enter 使用默认值：http://localhost:8080）

系统会打开浏览器窗口进行身份验证。授权后，命令会输出完整的 .mcp.json 配置，其中包含全部三个凭据，包括 GOOGLE_REFRESH_TOKEN。

复制该配置并粘贴到 .mcp.json 中，然后重新加载 Claude Code 窗口。

使用方法

配置完成后，你可以在 Claude Desktop 或 Claude Code 中使用这些工具：

Show me my Google Search Console sites

或

Get search performance data for example.com for the last 7 days

可用工具

1. list_sites

获取你有权访问的所有 Search Console 站点。

参数：无

示例：

Search Consoleのサイト一覧を教えて

2. get_analytics

查询指定日期范围内的搜索效果数据。

参数：

• siteUrl（必填）：站点 URL（例如："https://example.com/"）
• startDate（必填）：开始日期（YYYY-MM-DD）
• endDate（必填）：结束日期（YYYY-MM-DD）
• dimensions（可选）：维度数组 ["query", "page", "country", "device", "searchAppearance"]
• rowLimit（可选）：最大行数（默认值：100，最大值：25000）
• startRow（可选）：分页的起始行

示例：

example.comの過去7日間のトップクエリを取得して

example.comの2025年1月1日から1月31日までの、
ページ別とデバイス別のパフォーマンスを500件取得して

3. get_sitemaps

获取站点的站点地图信息。

参数：

• siteUrl（必填）：站点 URL

示例：

example.comのサイトマップ情報を確認して

4. inspect_url

检查特定 URL 的索引状态。

参数：

• siteUrl（必填）：站点 URL（例如："https://example.com/"）
• inspectionUrl（必填）：要检查的完整 URL

示例：

https://example.com/blog/article のインデックス状態を検査して

5. submit_url_for_indexing

使用 Indexing API 向 Google 提交 URL 以供编入索引，或请求移除 URL。

参数：

• url（必填）：要提交的完整 URL（例如："https://example.com/page"）
• type（可选）：通知类型——"URL_UPDATED"（默认值）或 "URL_DELETED"

示例：

https://example.com/new-article をインデックスに送信して

https://example.com/old-page を削除申請して（type: URL_DELETED）

注意：需要在 Google Cloud Console 中启用 Indexing API，并配置 https://www.googleapis.com/auth/indexing scope。

6. compare_periods

比较两个时间段之间的搜索效果指标（例如，本周与上周）。

参数：

• siteUrl（必填）：站点 URL（例如："https://example.com/"）
• currentStartDate（必填）：当前时间段的开始日期（YYYY-MM-DD）
• currentEndDate（必填）：当前时间段的结束日期（YYYY-MM-DD）
• previousStartDate（必填）：上一时间段的开始日期（YYYY-MM-DD）
• previousEndDate（必填）：上一时间段的结束日期（YYYY-MM-DD）
• dimensions（可选）：用于分组的维度数组
• rowLimit（可选）：最大行数（默认值：100，最大值：25000）

示例：

Compare this week vs last week performance for example.com

Compare query performance for example.com between January 2025 and December 2024
(currentStartDate: 2025-01-01, currentEndDate: 2025-01-31,
 previousStartDate: 2024-12-01, previousEndDate: 2024-12-31,
 dimensions: ["query"])

API 限制

• 每日配额：每个项目 2,000 次请求
• 每 100 秒：600 次请求
• 数据可用性：最多可查询 16 个月的历史数据
• 数据延迟：通常为 2-3 天

错误处理与重试逻辑

此 MCP 服务包含全面的错误处理功能：

自动重试

• 速率限制（429）：自动采用指数退避策略重试
• 服务器错误（5xx）：最多重试 3 次，每次延迟递增
• 暂时性故障：采用带抖动的智能重试逻辑，避免惊群效应

输入验证

所有工具都会在调用 API 前验证输入：

• 站点 URL：验证 URL 格式和结构
• 日期：验证 YYYY-MM-DD 格式和日期范围是否合理
• 行数限制：确保限制在 API 约束范围内（1-25,000）

详细错误消息

错误消息包括：

• 对错误原因的清晰说明
• HTTP 状态码
• 可用于解决问题的具体步骤

示例：

Access denied for list sites (403)
Verify your authentication credentials and ensure you have access to this Search Console property.
You may need to add your account as a test user in Google Cloud Console.

故障排除

设置问题

身份验证期间出现 “invalid_client” 错误

问题：运行设置命令时，出现 Error during authentication: invalid_client。

原因与解决方案：

1. CLIENT_ID 和 CLIENT_SECRET 不匹配

   • 确认它们来自 GCP Console 中同一个 OAuth 2.0 客户端
   • 直接从 Google Cloud Console 重新复制

2. “Authorized redirect URIs” 中缺少 http://localhost:8080

   • 如果你重复使用其他服务（Supabase、Firebase 等）的 OAuth 凭据
   • 解决方案：在 OAuth 2.0 客户端设置中的 “Authorized redirect URIs” 里添加 http://localhost:8080
   • 你可以设置多个重定向 URI（例如，https://xxx.supabase.co/auth/v1/callback 和 http://localhost:8080）

3. CLIENT_SECRET 已重新生成

   • 如果你在 GCP Console 中重置了密钥，请使用新密钥
   • 旧密钥会立即失效

出现 “could not determine executable to run” 错误

问题：npx google-search-console-mcp-server 执行失败，并提示 “could not determine executable to run”。

解决方案：包名称和可执行文件名称不同。请使用正确的 .mcp.json 配置：

{
  "mcpServers": {
    "google-search-console": {
      "command": "npx",
      "args": ["-y", "-p", "google-search-console-mcp-server", "google-search-console-mcp"],
      "env": { ... }
    }
  }
}

MCP 服务在 Claude Code 中显示 “✘ failed”

调试步骤：

1. 查看错误详情：

   • 在 Claude Code 的 MCP 状态屏幕中，按 Enter 键查看失败的服务
   • 向下滚动，查看 stderr（错误输出）

2. 手动测试：

   cd your-project-directory
   export GOOGLE_CLIENT_ID="your-id"
   export GOOGLE_CLIENT_SECRET="your-secret"
   export GOOGLE_REFRESH_TOKEN="your-token"
   npx -y google-search-console-mcp-server
   

3. 常见原因：

   • 未启用 Search Console API：在 GCP Console 中启用该 API
   • 凭据错误：确认 CLIENT_ID、CLIENT_SECRET 和 REFRESH_TOKEN
   • 令牌已过期：再次运行设置命令，获取新的 REFRESH_TOKEN
   • npx 缓存问题：清除 npx 缓存：rm -rf ~/.npm/_npx

4. 重新加载 Claude Code：修复 .mcp.json 后，重新加载窗口（Ctrl/Cmd + Shift + P → “Developer: Reload Window”）

运行时错误

“Missing required environment variables”

确保 .mcp.json 文件包含以下三个环境变量：GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET 和 GOOGLE_REFRESH_TOKEN。

“redirect_uri_mismatch”

确保已在 Google Cloud Console 的 OAuth 2.0 客户端设置中的 Authorized redirect URIs 中添加 http://localhost:8080（末尾不要加斜杠！）。

“Error 403: access_denied”

1. ⚠️ 最常见原因——OAuth 同意屏幕处于测试模式：
   • 在 GCP Console 中打开 “OAuth consent screen”
   • 如果 “Publishing status” 显示为 “Testing”，则必须将你的邮箱添加到 “Test users”
   • 在 “Test users” 部分中点击 “+ ADD USERS”
   • 添加你的 Google 账号邮箱（即用于身份验证的邮箱）
   • 点击 “Save”
   • 这是 access_denied 错误最常见的原因！
2. 未启用 API：在 GCP Console 中启用 “Google Search Console API”
3. 没有站点访问权限：确认你有权访问要查询的 Search Console 资源

“Invalid site URL format”

站点 URL 必须是完整 URL，例如：

• https://example.com/（适用于 URL 前缀资源）
• sc-domain:example.com（适用于网域资源）

“Date range too old”

Search Console 数据仅提供最近 16 个月的数据。

“Rate limit exceeded”

工具会自动采用退避策略重试。如果仍然触及限制：

• 每次请求之间等待几分钟
• 减少分析查询中的 rowLimit
• API 限制：每天 2,000 次请求，每 100 秒 600 次请求

令牌已过期

如果出现身份验证错误，你的刷新令牌可能已过期。重新运行身份验证设置：

npx -y -p google-search-console-mcp-server google-search-console-mcp-setup

将新的 GOOGLE_REFRESH_TOKEN 复制到 .mcp.json 中。

开发

构建

npm run build

监视模式

npm run dev

重新进行身份验证

node build/auth/setup-auth.js

项目结构

src/
├── index.ts                 # MCP server entry point
├── auth/
│   ├── google-auth.ts       # OAuth 2.0 client
│   └── setup-auth.ts        # Authentication CLI
├── tools/
│   ├── list-sites.ts        # List sites tool
│   ├── get-analytics.ts     # Search analytics tool
│   ├── get-sitemaps.ts      # Sitemap info tool
│   ├── inspect-url.ts       # URL inspection tool
│   ├── submit-url.ts        # Submit URL for indexing
│   └── compare-periods.ts   # Compare time periods
├── types/
│   └── index.ts             # Type definitions
└── utils/
    └── error-handler.ts     # Error handling & validation

安全说明

• 切勿将 .env 或 .mcp.json 文件提交到版本控制系统
• 妥善保管刷新令牌
• 尽可能使用只读范围（webmasters.readonly）
• 刷新令牌可提供持久访问权限，请妥善保管

许可证

MIT

贡献

欢迎贡献！欢迎提交问题或拉取请求。

---

资源

• Google Search Console API 文档
• Model Context Protocol
• Claude Code 文档