Google Search Console MCP Server

Google Search Console MCP 服务

🚀 简介：设置 MCP 服务

本教程将带你了解如何设置自己的 MCP Model Context Protocol 服务，将其添加到 Claude Desktop，并与 Google Search Console（GSC）数据集成。你可以比较不同时间段的数据，找出 SEO 改进之处；生成柱状图和折线图等可视化报告；还可以通过分析点击率、展示次数和排名变化，发现优化机会。

现在开始吧！🚀

🔹 本教程将介绍：

1. 生成 Google Cloud 凭据 – 创建并下载服务账号 JSON 密钥，以验证 API 访问权限。
2. 安装所需工具 – 确保系统已安装 Python、pip、uv 和 Git（可选）。
3. 设置 MCP 服务 – 克隆代码仓库、配置环境并安装 MCP 服务。
4. 启用 Search Console 洞察 – 验证 MCP 服务是否在 Claude Desktop 中正常运行，并开始使用高级搜索分析工具。

完成本指南后，Claude 将自动连接到 MCP 服务，你就可以轻松运行查询、可视化数据并优化网站的搜索表现。现在开始吧！🚀

🔹 你需要了解的内容

本教程面向初学者，无需掌握高级技术。不过，你应该熟悉如何在命令行（也称为终端或命令提示符）中运行命令。

在本指南中，你需要输入如下命令：

python --version
git clone <repository-url>

如果你从未使用过命令行，也不用担心！只需按步骤操作即可。

这些就是你需要了解的全部内容——现在开始吧！🚀

🎯 第 1 部分 - 生成 JSON 凭据文件

按照以下步骤，从 Google Cloud Console 创建并下载服务账号 JSON 密钥。如果你已有 JSON 凭据文件，可以跳过本部分。

📌 1. 前往 Google Cloud Console

🔗 访问 Google Cloud Console

📌 2. 选择项目

• 点击顶部的项目选择器。

• 选择一个现有项目，或创建一个新项目。

如果你要创建新项目：

启用 Search Console API

• 确保已选中你的新项目

• 点击API 和服务：

• 找到 Google Search Console API（你可能需要在顶部搜索）

• 点击**“启用”**

• 返回信息中心（点击**“Google Cloud”**图标）

📌 3. 打开 IAM 和管理部分

• 在左侧菜单中，前往**“IAM 和管理” > “服务账号”**。

📌 4. 创建新的服务账号

1. 点击**“创建服务账号”**。
2. 输入一个名称（例如，my-app-service-account）。
3. 点击**“创建并继续”**。

📌 5. 分配权限

• 选择一个角色（例如，Editor、Owner）。
• 点击**“继续”**。

📌 6. 跳过授予用户访问权限（可选）

• 点击**“完成”**（无需添加用户）。

📌 7. 生成 JSON 密钥

1. 在列表中找到你的服务账号。
2. 点击右侧的三个点（⋮），然后选择**“管理密钥”**。
3. 点击**“添加密钥” > “创建新密钥”**。
4. 选择 “JSON” 格式并点击**“创建”**。
5. ✅ JSON 文件将自动下载。
6. 复制 JSON 文件的路径（右键点击 +“复制为路径”）

📌 8. 将服务账号添加到 Google Search Console

1. 打开 Google Search Console。
2. 选择网站资源。
3. 点击设置（左下角）。
4. 在用户和权限下，点击添加用户。
5. 输入服务账号邮箱（来自第 4 步）。
6. 分配权限：
   • 受限（仅查看数据）。
   • 完全（查看和管理资源）。
7. 点击添加。

---

🎯 第 2 部分 - 安装所需工具

开始使用项目之前，请确保已安装必要的工具。按照以下步骤检查是否一切就绪。

📌 1. 检查是否已安装 Python

运行以下命令，检查系统上是否已安装 Python：

在 Windows 上：

python --version

在 Linux/macOS 上：

python3 --version

如果已安装 Python，你会看到版本号。如果没有，请从 🔗 下载 Python 下载并安装。

📌 2. 检查是否已安装 pip

pip 是 Python 的包管理器。运行以下命令，检查是否已安装：

在 Windows 上：

pip --version

在 Linux/macOS 上：

pip3 --version

如果未安装 pip，请参阅官方安装指南 🔗 下载 pip

📌 3. 检查是否已安装 uv

uv 是 Python 包和项目管理器。运行以下命令，检查是否已安装：

在 Linux/macOS/Windows 上：

uv --version

如果未安装 uv，请参阅官方安装指南 🔗 下载 uv

📌 4. 检查是否已安装 Claude Desktop

如果尚未安装 Claude Desktop，请参阅官方安装指南 🔗 下载 Claude Desktop 。

📌 5. 检查是否已安装 Git（可选）

运行以下命令，检查系统上是否已安装 Git：

在 Linux/macOS/Windows 上：

git --version

如果已安装 Git，你会看到版本号。如果没有，你仍然可以下载程序文件，或者从 🔗 下载 Git 下载并安装 Git。

---

🎯 第 3 部分 - 将 MCP 服务添加到 Claude Desktop

设置说明

1. 克隆代码仓库

在要下载文件的文件夹中打开一个新终端。运行以下命令：

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

如果没有安装 Git：

• 下载 ZIP 文件：

2. 创建并激活虚拟环境

# Windows
uv venv
.venv\Scripts\activate

# macOS/Linux
uv venv
source .venv/bin/activate

3. 安装依赖项

# Windows/macOS/Linux
uv sync

4. 安装 MCP 服务

添加 JSON 凭据文件的路径，然后运行以下命令：

mcp install server.py -v GOOGLE_APPLICATION_CREDENTIALS=<path to credentials file>

请确保将 <path to credentials file> 替换为 JSON 凭据文件的路径，例如 C:\Users\Me\Downloads\credentials.json 。

5. 重启 Claude Desktop

你可能需要在任务管理器中结束 Claude 任务。

---

🎯 第 4 部分 - 获取 Search Console 洞察

打开 Claude Desktop。如果 MCP 服务已正确配置，你应该会在聊天框中看到另外 5 个可用工具：

你可以让 Claude 执行各种 Search Console 分析任务来使用这些工具。在调用工具之前，Claude 会请求许可。点击其中一个“允许”选项即可使用 MCP 服务：

入门提示词

• “列出我在 Google Search Console 中所有已验证的网站”
• “显示 example.com 在 2025 年 1 月 1 日至 1 月 31 日的搜索分析数据”
• “比较 example.com 上个月和前一个月的搜索表现”
• “过去 30 天点击量最高的 10 个网页是什么？”
• “按周显示过去 3 个月的搜索趋势”

数据可视化提示词

• “生成一个柱状图，展示过去一个月点击量最高的 5 个页面”
• “创建一个折线图，展示过去 90 天的展示次数趋势”
• “可视化比较我网站移动端和桌面端流量的点击率”
• “绘制 example.com 按国家划分的搜索表现热力图”
• “创建一个饼图，展示按设备类型划分的流量分布”
• “生成一个散点图，比较点击率与我排名最高的 50 个查询的排名位置”
• “通过可视化图表展示按搜索类型（网页、图片、视频）划分的流量来源”
• “创建一个堆叠面积图，展示随时间变化的点击量和展示次数”
• “通过对比图表可视化展示搜索表现的周环比变化”
• “生成一份包含多张图表的网站 SEO 表现可视化报告”

Search Console 分析提示词

• “找出展示次数高但点击率低、值得优化的关键词”
• “显示过去一个月排名下降的页面”
• “找出我的网站过去 30 天开始获得排名的新关键词”
• “分析哪些移动端页面与桌面端相比存在最大的表现差距”
• “显示排名在第 2 页（第 11–20 位）、有望提升至第 1 页的查询”
• “识别过去一年搜索流量中的季节性趋势”
• “比较 3 月 1 日网站重新设计前后的自然流量”
• “根据展示次数与点击量，显示增长潜力最高的国家”
• “分析我排名最高的 100 个查询的平均排名位置与点击率之间的相关性”
• “根据潜在流量增长，生成一份按优先级排序的优化机会清单”

可用工具

list_sites

列出 Google Search Console 账号中所有已验证的网站。

query_search_analytics

Parameters:
- site_url: Full URL of your website (e.g., https://www.example.com/)
- start_date: Start date in YYYY-MM-DD format
- end_date: End date in YYYY-MM-DD format
- dimensions: List of dimensions (query, page, device, country, date)
- search_type: Type of search results (web, image, video, news, discover, googleNews)
- row_limit: Number of rows to return (max 25000)

compare_time_periods

Parameters:
- site_url: Full URL of your website
- current_start_date: Start date for current period in YYYY-MM-DD format
- current_end_date: End date for current period in YYYY-MM-DD format
- previous_start_date: Start date for previous period in YYYY-MM-DD format
- previous_end_date: End date for previous period in YYYY-MM-DD format
- dimensions: List of dimensions (query, page, device, country, date)
- search_type: Type of search results
- row_limit: Number of rows to return

get_top_performing_content

Parameters:
- site_url: Full URL of your website
- start_date: Start date in YYYY-MM-DD format
- end_date: End date in YYYY-MM-DD format
- metric: Metric to sort by (clicks, impressions, ctr, position)
- limit: Number of results to return

get_search_trends

Parameters:
- site_url: Full URL of your website
- start_date: Start date in YYYY-MM-DD format
- end_date: End date in YYYY-MM-DD format
- interval: Time interval for grouping (day, week, month)

🛠 故障排除

如果在设置或使用 MCP 服务时遇到问题，请尝试以下解决方案：

1️⃣ 重启 Claude Desktop

有时，工具不会立即显示。重启 Claude Desktop，然后重试。 重启前，你可能需要在任务管理器（Windows）或活动监视器（Mac）中结束 Claude 进程。

2️⃣ 等待几分钟

设置 MCP 服务后，新工具可能需要几分钟才能加载。 如果工具没有立即显示，请等待几分钟后重试。

3️⃣ 检查 JSON 凭据文件

确保服务账号 JSON 文件位于可访问的文件夹中。 避免将其放在受限文件夹或仅管理员可访问的文件夹中（例如 Windows 上的 C:\Program Files\ 或 macOS 上的 ~/Library/）。 如有必要，请将其移至更容易访问的位置，例如“文稿”或“桌面”文件夹。

:four: 检查 Claude 配置

前往 File => Settings，然后点击 Developer 选项卡。点击 Search Console Analytics 后，其状态应显示为“running”。如果不是，可能会出现错误消息，说明导致连接问题的原因。如果你看不到下图所示的 Settings，请确保使用的是最新版本的 Claude Desktop：🔗 下载 Claude Desktop。

点击 Edit Config，并在文本编辑器中打开 'claude_desktop_config.json'。其中应包含：

{
  "mcpServers": {
    "Search Console Analytics": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "google-api-python-client",
        "--with",
        "google-auth",
        "--with",
        "mcp[cli]",
        "--with",
        "pandas",
        "mcp",
        "run",
        "C:\\Documents\\gsc-mcp-server\\server.py"
      ],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "C:\\Users\\Path\\To\\Credentials\\gscaccess-credentials.json"
      }
    }
  }
}

如果其中内容不同，请将这些数据粘贴到文件中，并确保更新 server.py 文件和凭据文件的路径。请按示例对反斜杠字符进行转义。然后重启 Claude。

Mac 用户：修复“spawn uv ENOENT”错误

如果打开 Claude Desktop 时看到 “spawn uv ENOENT” 错误，说明 uv 尚未安装或未在系统路径中找到。如果已安装 uv，可以尝试在 Claude 配置中添加完整路径。

1️⃣ 更新 Claude Desktop 配置

打开 Claude Desktop，前往 File > Settings > Developer。 点击 “Search Console Analytics”，然后选择 Edit Config。 在 claude_desktop_config.json 中找到 "command": "uv" 条目。 将 "uv" 替换为 uv 的完整路径，通常为：/Users/YOURUSERPROFILENAME/.local/bin/uv

运行此命令以获取 uv 的安装路径：

which -a uv

此命令会显示 uv 的所有安装路径。如果你只能看到 /Library/Frameworks/Python.framework/Versions/3.**/bin/uv，则需要 🔗 下载 uv，然后返回第 3 部分。

保存文件并重启 Claude Desktop。

2️⃣ 尝试另一种 uv 安装方法

如果上述方法不起作用，uv 可能没有正确安装。尝试使用 Homebrew 安装：

brew install uv

如果问题仍然存在，请重新检查操作步骤，确保所有内容都已正确设置。🚀