Google Search Console MCP server for SEOs

面向 SEO 的 Google Search Console MCP 服务

一个模型上下文协议（MCP）服务，可将 Google Search Console（GSC）连接到 AI 助手，让你通过自然语言对话分析 SEO 数据。支持 Claude Desktop、Cursor、Codex CLI、Gemini CLI、Antigravity 以及任何其他兼容 MCP 的客户端。

跳过设置，获取更多功能。 更先进的托管版本——一键登录，并新增 GA4 工具。适用于 Claude Desktop、Claude Code、Claude.ai、Codex、Cursor 和任何 MCP 客户端。仅限 100 个名额。 → Advanced GSC MCP（托管版）

---

最新动态

[0.4.1] — 2026 年 9 月

• check_indexing_issues 现已并发运行 — 与 #31 的修复相同，因此针对 sc-domain:* 媒体资源执行 10 个 URL 的批次检查时不再超时。感谢 @kuldiph。（#55）
• 移除了 get_search_by_page_query 中遗留的无效 orderBy（Search Analytics API 会忽略它）。感谢 @kuldiph。（#55）

[0.4.0] — 2026 年 9 月

• 现可显示富媒体搜索结果问题 — inspect_url_enhanced 和 batch_url_inspection 现在会从正确的 API 路径读取富媒体搜索结果问题，因此标记问题会被报告，而不会再被静默忽略。感谢 @patrickweh。（#46、#48）
• batch_url_inspection 现已并发运行 — 针对 sc-domain:* 媒体资源执行 10 个 URL 的批次检查时不再超时。感谢 @remotesensei。（#31）
• 修正了 compare_search_periods 的变化值 — 现在第 1 个周期是分析周期，第 2 个周期是基准周期，因此增长会显示为增长（而非下降）。感谢 @JKdreaming。（#42）
• get_advanced_search_analytics 排序现已生效 — sort_by/sort_direction 现在会被应用，而不再被静默忽略。感谢 @kuldiph。（#54）
• 强化了错误处理 — 替换了裸 except: 子句，避免致命信号被吞掉。感谢 @kuldiph。（#53）
• 注意： batch_url_inspection 将每个 URL 的 verdict 字段重命名为 index_verdict，以便与富媒体搜索结果判定区分开来。

[0.3.3] — 2026 年 7 月

• 修复了因 mcp 2.0 导致的新安装无法运行的问题 — 固定使用 mcp[cli]<2.0.0。mcp SDK 2.0.0（于 2026-07-28 发布）移除了 mcp.server.fastmcp 模块，因此每次全新安装 uvx mcp-search-console 都会在启动时因 ModuleNotFoundError: No module named 'mcp.server.fastmcp' 而崩溃。现在新安装会再次解析到可正常工作的 1.x SDK，无需使用 --with "mcp<2" 变通方法。

[0.3.2] — 2026 年 4 月

• 修复了 uvx 的 OAuth 浏览器流程 — 移除了阻止 macOS 上作为 MCP 子进程运行时打开浏览器登录窗口的 isatty 限制。现在 OAuth 开箱即用，使用 uvx 时无需手动运行终端。
• 新增 get_capabilities 工具 — 调用它即可一次性获取可用工具的完整列表和当前身份验证状态。当 AI 助手不确定有哪些可用工具时，这很有用。
• 优化了身份验证错误消息 — 凭据缺失或过期时，所有工具现在都会明确告知你该怎么做。

---

它能做什么？

资产管理

• 在一处查看所有 GSC 资产
• 获取验证详情和所有权信息
• 在你的账号中添加或移除资产

搜索分析与报告

• 了解哪些查询为你的网站带来访客
• 跟踪展示次数、点击次数和点击率
• 分析效果趋势并比较不同时段
• 通过 AI 助手创建的图表可视化数据

URL 检查与编入索引

• 检查特定网页是否存在编入索引问题
• 查看 Google 上次抓取网页的时间
• 一次检查多个 URL，以找出规律

站点地图管理

• 查看所有站点地图及其状态
• 提交新的站点地图
• 检查错误或警告

---

可用工具

工具	功能	需要提供的信息
get_capabilities	列出所有工具并显示身份验证状态 — 不确定时请先调用	无
list_properties	显示所有 GSC 资产	无
get_site_details	查看特定网站的详情	网站 URL
get_search_analytics	查看带有点击次数、展示次数、点击率和排名的热门查询和网页	网站 URL、时间段
get_performance_overview	查看网站效果摘要	网站 URL、时间段
compare_search_periods	比较两个时间段的效果	网站 URL、两个日期范围
get_search_by_page_query	查看为特定网页带来流量的搜索词	网站 URL、网页 URL
get_advanced_search_analytics	按国家/地区、设备、查询和网页筛选分析数据	网站 URL
inspect_url_enhanced	查看 URL 的详细抓取/编入索引状态	网站 URL、网页 URL
batch_url_inspection	一次检查最多 10 个 URL	网站 URL、URL 列表
check_indexing_issues	检查多个 URL 是否存在编入索引问题	网站 URL、URL 列表
get_sitemaps	列出网站的所有站点地图	网站 URL
list_sitemaps_enhanced	查看站点地图的详细信息，包括错误和警告	网站 URL
manage_sitemaps	提交或删除站点地图	网站 URL、操作
reauthenticate	重新运行 OAuth 浏览器登录（切换账号）	无

让你的 AI 助手“调用 get_capabilities”，即可查看全部 20 个工具。

---

---

开始使用

第 1 步 — 设置 Google API 凭据

配置任何客户端前，你都需要先准备凭据。选择一种方法：

选项 A — OAuth（推荐 — 使用你自己的 Google 账号）

1. 前往 Google Cloud Console 并创建或选择一个项目
2. 启用 Search Console API
3. 前往 Credentials → 创建凭据 → OAuth 客户端 ID
4. 配置 OAuth 同意屏幕，选择 Desktop app，然后点击创建
5. 下载 JSON 文件 — 将其保存到一个永久位置（例如 ~/Documents/client_secrets.json）

首次使用时，系统会打开浏览器窗口，要求你登录 Google 账号。之后，令牌会被保存，无需再次通过浏览器操作。

选项 B — 服务账号（适用于自动化或团队使用）

1. 前往 Google Cloud Console 并创建或选择一个项目
2. 启用 Search Console API
3. 前往 Credentials → Create Credentials → Service Account
4. 前往 Keys 标签页 → Add Key → Create new key → JSON → Download
5. 将文件保存在固定位置（例如 ~/Documents/service_account.json）
6. 将服务账号邮箱添加到 GSC 媒体资源：Search Console → Settings → Users and permissions → Add user → Full access

🎥 观看本节的逐步设置教程

更新于 2026 年 — 涵盖完整安装流程，使用新的 uvx 方法，从设置 Google 凭据到首次成功查询。

---

步骤 2 — 安装

选项 A — uvx（推荐）

无需克隆、无需安装 Python，也无需虚拟环境。uvx 会自动下载并运行服务，并保持其为最新版本。

安装 uv — 打开终端并按顺序运行以下三条命令：

# 1. Download and install
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Activate in the current Terminal session
source $HOME/.local/bin/env

# 3. Make it permanent for all future sessions
echo 'source $HOME/.local/bin/env' >> ~/.zshrc

验证：

uv --version

为什么需要运行三条命令？ 安装程序会将 uv 放入 ~/.local/bin，但当前已打开的终端会话尚未识别该目录。第 2 步会立即启用它。第 3 步可确保以后每个终端窗口都能自动识别它。

现在配置你的 AI 客户端：

---

Claude Desktop

配置文件：~/Library/Application Support/Claude/claude_desktop_config.json

OAuth：

{
  "mcpServers": {
    "gscServer": {
      "command": "/FULL/PATH/TO/uvx",
      "args": ["mcp-search-console"],
      "env": {
        "GSC_OAUTH_CLIENT_SECRETS_FILE": "/full/path/to/client_secrets.json"
      }
    }
  }
}

服务账号：

{
  "mcpServers": {
    "gscServer": {
      "command": "/FULL/PATH/TO/uvx",
      "args": ["mcp-search-console"],
      "env": {
        "GSC_CREDENTIALS_PATH": "/full/path/to/service_account.json",
        "GSC_SKIP_OAUTH": "true"
      }
    }
  }
}

---

Cursor

配置文件：~/.cursor/mcp.json

OAuth：

{
  "mcpServers": {
    "gscServer": {
      "command": "/FULL/PATH/TO/uvx",
      "args": ["mcp-search-console"],
      "env": {
        "GSC_OAUTH_CLIENT_SECRETS_FILE": "/full/path/to/client_secrets.json"
      }
    }
  }
}

---

Codex CLI

配置文件：~/.codex/config.toml

OAuth：

[mcp_servers.gscServer]
command = "/FULL/PATH/TO/uvx"
args = ["mcp-search-console"]
enabled = true
env = { GSC_OAUTH_CLIENT_SECRETS_FILE = "/full/path/to/client_secrets.json" }

服务账号：

[mcp_servers.gscServer]
command = "/FULL/PATH/TO/uvx"
args = ["mcp-search-console"]
enabled = true
env = { GSC_CREDENTIALS_PATH = "/full/path/to/service_account.json", GSC_SKIP_OAUTH = "true" }

---

查找 uvx 路径： 在 macOS/Linux 上安装 uv 后，在终端运行 which uvx（通常是 /Users/YOUR_NAME/.local/bin/uvx）。在 Windows 上，在 PowerShell 中运行 Get-Command uvx | Select-Object -ExpandProperty Source（或在 cmd 中运行 where uvx）——通常是 C:\Users\YOUR_NAME\.local\bin\uvx.exe。将上述配置中的 /FULL/PATH/TO/uvx 替换为该路径。

为什么要使用完整路径？ Claude Desktop 和 Cursor 这类 GUI 应用启动时不会读取你的 shell 配置（~/.zshrc），因此无法识别 ~/.local/bin。使用完整路径可以确保应用无论以何种方式启动都能正常运行。如果看到 spawn uvx ENOENT 错误，这就是解决方法。

保存配置后，完全退出应用（Cmd+Q）并重新打开。

使用 OAuth 时：首次使用会自动打开浏览器窗口供你登录。之后令牌会被缓存，不会再提示你登录。

---

选项 B — 克隆（高级）

更喜欢通过视频了解此方法？ 以下教程将逐步介绍克隆安装流程，包括虚拟环境设置、依赖项和配置：

如果你想修改代码或运行特定的本地版本，请使用此方法。此方法通过上述视频教程介绍凭据设置步骤。

需要 Python 3.11+。 此服务无法在 Python 3.10 或更早版本上启动；如果由 Claude Desktop 这类 GUI 客户端启动，还会静默失败（不会显示工具，也不会写入日志文件）。使用 python --version 检查你的版本。如果版本低于 3.11，请安装 Python 3.11 或更高版本并重新创建虚拟环境。uvx 方法（选项 A）会为你管理 Python 版本，因此完全不会遇到此问题，是 Windows 上的推荐方式。

克隆仓库：

git clone https://github.com/AminForou/mcp-gsc.git
cd mcp-gsc

或者点击本页顶部绿色的 Code 按钮下载 ZIP 并解压。

设置环境：

uv venv .venv
uv pip install -r requirements.txt

配置 AI 客户端（以 Claude Desktop 为例）：

OAuth：

{
  "mcpServers": {
    "gscServer": {
      "command": "/full/path/to/mcp-gsc/.venv/bin/python",
      "args": ["/full/path/to/mcp-gsc/gsc_server.py"],
      "env": {
        "GSC_OAUTH_CLIENT_SECRETS_FILE": "/full/path/to/client_secrets.json"
      }
    }
  }
}

服务账号：

{
  "mcpServers": {
    "gscServer": {
      "command": "/full/path/to/mcp-gsc/.venv/bin/python",
      "args": ["/full/path/to/mcp-gsc/gsc_server.py"],
      "env": {
        "GSC_CREDENTIALS_PATH": "/full/path/to/service_account.json",
        "GSC_SKIP_OAUTH": "true"
      }
    }
  }
}

Mac 路径示例：

• Python：/Users/yourname/Documents/mcp-gsc/.venv/bin/python
• 脚本：/Users/yourname/Documents/mcp-gsc/gsc_server.py

---

第 3 步 — 测试

向你的 AI 助手提问：“列出我的 GSC 资源”

如果你看到了自己的资源，说明运行正常。如果没有，请询问：“调用 get_capabilities”，查看身份验证状态并诊断问题。

---

环境变量参考

变量	必需	默认值	说明
GSC_OAUTH_CLIENT_SECRETS_FILE	仅 OAuth	—	OAuth 客户端机密 JSON 文件的绝对路径。使用 uvx 时始终必需。
GSC_CREDENTIALS_PATH	仅服务账号	—	服务账号 JSON 密钥的绝对路径。使用 uvx 时始终必需。
GSC_SKIP_OAUTH	否	false	设置为 "true" 以强制使用服务账号身份验证并完全跳过 OAuth
GSC_DATA_STATE	否	"all"	"all" 与 GSC 信息中心匹配。"final" 仅返回已确认的数据（延迟 2–3 天）。
GSC_ALLOW_DESTRUCTIVE	否	false	设置为 "true" 以启用添加/删除网站和删除站点地图工具

---

Cursor Marketplace

支持一键安装 — 在 Cursor Marketplace 中搜索 mcp-search-console。

安装后，配置你的凭据（参见上面的第 1 步），然后直接在 Cursor Agent 聊天中使用捆绑的技能：

技能	调用方式	功能
seo-weekly-report	“为 example.com 运行 SEO 周报”	提供完整的 28 天效果摘要，包含周期对比和热门查询
cannibalization-check	“检查 example.com 是否存在关键词蚕食”	查找多个页面相互竞争的查询；建议保留哪些页面
indexing-audit	“审核我排名靠前页面的索引情况”	批量检查排名靠前的 20 个页面，并返回按优先级排序的修复清单
content-opportunities	“查找 example.com 的内容机会”	找出排名第 11–20 位且展示次数高、点击率低的查询

---

示例提示词

工具	示例提示词
list_properties	"列出我所有的 GSC 资源，并告诉我哪些资源已编入索引的页面最多。"
get_search_analytics	"显示 mywebsite.com 过去 30 天内排名前 20 的搜索查询，标出点击率低于 2% 的查询，并建议如何改进标题。"
get_performance_overview	"创建 mywebsite.com 过去 28 天的可视化效果概览，找出任何异常下降或峰值，并说明可能的原因。"
check_indexing_issues	"检查以下页面是否存在编入索引问题：mywebsite.com/product、mywebsite.com/services、mywebsite.com/about"
inspect_url_enhanced	"全面检查 mywebsite.com/landing-page，并提供可执行的建议。"
compare_search_periods	"比较我的网站在 1 月和 2 月的效果。哪些查询提升最大？"
get_advanced_search_analytics	"分析展示次数高但排名低于 10 的查询，仅筛选美国的移动流量。"

---

故障排除

spawn uvx ENOENT 或 command not found: uvx

你的 AI 客户端找不到 uvx。请使用完整路径，而不是只写 uvx：

# Find your full path (macOS/Linux):
which uvx
# Typically: /Users/YOUR_NAME/.local/bin/uvx

# Find your full path (Windows PowerShell):
Get-Command uvx | Select-Object -ExpandProperty Source
# Typically: C:\Users\YOUR_NAME\.local\bin\uvx.exe

在配置中，将 "command": "uvx" 替换为完整路径（例如 "command": "/Users/YOUR_NAME/.local/bin/uvx"）。

安装后立即运行 uv --version 时提示 "command not found"

安装程序会更新 ~/.local/bin，但当前终端会话还无法识别它。运行：

source $HOME/.local/bin/env

然后将它永久添加：

echo 'source $HOME/.local/bin/env' >> ~/.zshrc

身份验证失败／找不到凭据文件

请确保使用凭据文件的绝对路径，而不是相对路径，也不要使用 ~/。例如：

/Users/yourname/Documents/client_secrets.json   ✅
~/Documents/client_secrets.json                 ✅
client_secrets.json                              ❌

MCP 仅在 Claude 桌面应用中可用，在网站上不可用

MCP 服务在你的计算机上本地运行。它仅在 Claude 桌面应用中可用（从 claude.ai/download 下载），不能在 claude.ai 浏览器界面中使用。

AI 客户端配置问题

1. 确保配置中的所有文件路径都是正确的绝对路径
2. 修改配置后，完全退出（Cmd+Q）并重新打开应用——仅关闭窗口是不够的
3. 请你的 AI 助手“调用 get_capabilities”——它会报告准确的身份验证状态和错误

---

安全：破坏性操作

默认情况下，add_site、delete_site 和 delete_sitemap 均处于禁用状态。若要启用它们：

"GSC_ALLOW_DESTRUCTIVE": "true"

---

远程部署与 Docker（高级）

标准配置会在本地运行服务。本节仅适用于希望在远程服务或容器中运行它的用户。

HTTP 传输

MCP_TRANSPORT=sse MCP_HOST=0.0.0.0 MCP_PORT=3001 python gsc_server.py

变量	默认值	描述
MCP_TRANSPORT	stdio	设置为 sse 以用于网络／远程场景
MCP_HOST	127.0.0.1	绑定的主机
MCP_PORT	3001	绑定的端口

Docker

docker build -t mcp-gsc .

docker run \
  -e MCP_TRANSPORT=sse \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=3001 \
  -e GSC_CREDENTIALS_PATH=/app/credentials.json \
  -v /path/to/credentials.json:/app/credentials.json \
  -p 3001:3001 \
  mcp-gsc

---

相关工具

Advanced GSC Visualizer — 一款 Chrome 扩展程序（拥有 14,000+ 名用户），提供交互式图表、一键导出最多 25,000 行数据、关键词蚕食检测和 AI 助手，所有功能都可直接在 Google Search Console 中使用。由同一位作者开发。从 Chrome 网上应用店安装 →

---

参与贡献

发现了 Bug 或有改进建议？请在 GitHub 上提交 Issue 或 Pull Request。

感谢所有报告问题并贡献修复的用户，包括 @patrickweh、@remotesensei、 @JKdreaming 和 @kuldiph。

---

许可证

MIT 许可证。详情请参阅 LICENSE 文件。

---

更新日志

[0.4.1] — 2026 年 9 月

• check_indexing_issues 现在会并发检查 URL（与 #31 的修复相同），避免针对 sc-domain:* 资源检查完整的 10 个 URL 批次时发生超时。（修复 #55；感谢 @kuldiph）
• 从 get_search_by_page_query 中移除了遗留的 orderBy——这是一个 Search Analytics API 会忽略的无效字段，与 #54 中的清理保持一致。（修复 #55；感谢 @kuldiph）

[0.4.0] — 2026 年 9 月

• 修复了 inspect_url_enhanced 和 batch_url_inspection 中的富媒体搜索结果问题报告——问题现在从 detectedItems[].items[].issues[]（issueMessage）读取，这是 API 实际返回的字段，因此问题不会再被悄然遗漏。（修复 #46、#48；感谢 @patrickweh）
• batch_url_inspection 现在会并发检查 URL，因此即使针对较慢的 sc-domain:* 资源，完整的 10 个 URL 批次也能在客户端超时前完成。（修复 #31；感谢 @remotesensei）
• compare_search_periods 现在会计算第 1 个时间段相对于第 2 个时间段的变化（以第 2 个时间段作为百分比基准，正值表示第 1 个时间段表现更好），并说明了方向。（修复 #42；感谢 @JKdreaming）
• get_advanced_search_analytics 现在会在客户端应用 sort_by/sort_direction，而不是发送 Search Analytics API 会忽略的 orderBy。（修复 #54；感谢 @kuldiph）
• 将三处裸 except: 子句替换为 except Exception:，因此不再会吞掉 KeyboardInterrupt/SystemExit。（修复 #53；感谢 @kuldiph）
• 重大变更： batch_url_inspection 将每个 URL 的 verdict 字段重命名为 index_verdict。

[0.3.3] — 2026 年 7 月

• 固定为 mcp[cli]>=1.3.0,<2.0.0。mcp SDK 2.0.0 移除了 mcp.server.fastmcp，导致所有全新 uvx 安装都因 ModuleNotFoundError 而无法使用。将版本限制在 2.0 以下即可恢复正常安装。（修复 #41）

[0.3.2] — 2026 年 4 月

• 修复了适用于 uvx 的 OAuth 浏览器流程——移除了阻止 macOS 上以 MCP 子进程运行时打开 OAuth 浏览器窗口的 isatty 限制。现在 OAuth 与 uvx 开箱即用。
• get_capabilities 工具——一次调用即可返回按类别分组的所有可用工具以及实时身份验证状态。
• 更清晰的身份验证错误消息——当凭据缺失或过期时，所有工具现在都会明确提示调用 reauthenticate。
• 改进了 list_properties 的描述——在使用延迟工具加载的客户端中，可实现更准确的语义工具发现。

[0.3.1] — 2026 年 4 月

• 修复了 list_properties 屏蔽实际身份验证错误的问题；缺少凭据时会立即失败。

[0.3.0] — 2026 年 4 月

• Cursor Marketplace 插件，内置 4 项 SEO 技能
• 将令牌稳定存储在平台用户配置目录中（升级 uvx 后仍会保留）
• 所有数据工具均输出结构化 JSON
• 39 项单元测试

[0.2.2] — 2026 年 4 月

• 为破坏性工具提供安全模式（默认禁用）
• 用于远程部署的 HTTP/SSE 传输
• Dockerfile

[0.2.1] — 2026 年 3 月

• 新增用于切换 Google 账号的 reauthenticate 工具
• 修复站点地图 TypeError 崩溃
• 修复域名资源的 404 错误

[0.2.0] — 2026 年 3 月

• 默认设置 dataState: "all"（与 GSC 信息中心一致）
• 灵活的 row_limit 参数（最多 500）
• 支持高级分析的多维度筛选

[0.1.0] — 首次发布

• 提供 19 个工具，涵盖资源管理、搜索分析、URL 检查和站点地图管理
• 支持 OAuth 和服务账号身份验证