面向 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 个席位。 → 高级 GSC MCP（托管版）

更新内容

[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 助手不确定有哪些工具可用时非常有用。

• 更好的认证错误提示 — 所有工具现在都会在凭据缺失或过期时明确告诉你该怎么做。

Related MCP server: Google Search Console MCP Server

它能做什么？

属性管理

• 在一个地方查看你的所有 GSC 属性

• 获取验证详情和所有权信息

• 从你的账户中添加或移除属性

搜索分析与报告

• 发现哪些查询为你的网站带来访客

• 跟踪展示次数、点击次数和点击率

• 分析表现趋势并比较时间段

• 通过 AI 助手创建的图表可视化数据

网址检查与索引

• 检查特定页面是否存在索引问题

• 查看 Google 上次抓取你页面的时间

• 一次检查多个网址以识别规律

站点地图管理

• 查看所有站点地图及其状态

• 提交新的站点地图

• 检查错误或警告

可用工具

让 AI 助手"调用 get_capabilities"即可获取全部 20 个工具的完整列表。

快速开始

第 1 步 — 设置 Google API 凭据

在配置任何客户端之前，你需要先准备好凭据。选择以下任一方式：

方式 A — OAuth（推荐——使用你自己的 Google 账户）

1. 前往 Google Cloud Console 创建或选择一个项目

2. 启用 Search Console API

3. 前往 凭据 → 创建凭据 → OAuth 客户端 ID

4. 配置 OAuth 同意屏幕，选择桌面应用，点击创建

5. 下载 JSON 文件——保存到某个固定位置（例如 ~/Documents/client_secrets.json）

首次使用时，浏览器窗口会自动打开，要求你登录 Google 账户。之后令牌会被保存，无需再次进行浏览器交互。

方式 B — 服务账户（适用于自动化或团队使用）

1. 前往 Google Cloud Console 创建或选择一个项目

2. 启用 Search Console API

3. 前往 凭据 → 创建凭据 → 服务账户

4. 前往"密钥"标签页 → 添加密钥 → 创建新密钥 → JSON → 下载

5. 将文件保存到某个固定位置（例如 ~/Documents/service_account.json）

6. 将服务账户邮箱添加到你的 GSC 属性：Search Console → 设置 → 用户和权限 → 添加用户 → 完全访问权限

🎥 观看本部分的逐步设置教程

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"以查看认证状态并诊断问题。

环境变量参考

Cursor 市场

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

安装后，配置你的凭据（见上文步骤 1），然后直接在 Cursor Agent 聊天中直接使用内置技能：

示例提示词

故障排查

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 Desktop 应用中有效，在网页版中无效

MCP 服务器在你的机器上本地运行。它只能在 Claude Desktop 应用（从 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

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。

许可证

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

更新日志

[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 浏览器流程 — 移除了阻止 OAuth 浏览器窗口在 macOS 上作为 MCP 子进程运行时打开的 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 工具

• 修复了 sitemap 的 TypeError 崩溃

• 修复了域名资源的 404 错误

[0.2.0] — 2026 年 3 月

• 默认使用 dataState: "all"（与 GSC 仪表板一致）

• 灵活的 row_limit 参数（最多 500）

• 用于高级分析的多维度筛选

[0.1.0] — 初始版本

• 19 个工具，涵盖资源管理、搜索分析、URL 检查和 sitemap 管理

• OAuth 和服务账号身份验证