STARWARCLOUD STARWAR.AI
返回市场
谷歌搜索控制台-MCP

谷歌搜索控制台-MCP

作者：surendranb17 星标更新：2025-06-04
安装使用来源：spider==github.com

项目介绍

<p align="center"> <img src="logo.svg" alt="Google 搜索控制台 MCP 标志" width="120" /> </p>

Google 搜索控制台 MCP 服务器

PyPI 版本 PyPI 下载量 GitHub 星标 GitHub 分支 Python 3.8+ MIT 许可证 用心制作

连接 Google 搜索控制台数据到 Claude、Cursor 和其他 MCP 客户端。使用自然语言查询您的网站搜索性能数据，访问所有 GSC 维度和指标。

兼容： Claude、Cursor 和其他 MCP 客户端。

预备条件

检查您的 Python 设置：

# 检查 Python 版本（需要 3.8 或更高版本）
python --version
python3 --version

# 检查 pip
pip --version
pip3 --version

必需：

  • Python 3.8 或更高版本
  • 包含数据的 Google 搜索控制台属性
  • 具有搜索控制台 API 访问权限的服务账户

第一步：设置 Google 搜索控制台凭证

在 Google Cloud 控制台中创建服务账户

  1. 转到 Google Cloud 控制台
  2. 创建或选择项目：
    • 新项目：点击“新建项目” → 输入项目名称 → 创建
    • 现有项目：从下拉菜单中选择
  3. 启用搜索控制台 API：
    • 前往“API和服务” → “库”
    • 搜索“搜索控制台 API” → 点击“启用”
  4. 创建服务账户：
    • 前往“API和服务” → “凭据”
    • 点击“创建凭据” → “服务账户”
    • 输入名称（例如，“gsc-mcp-server”）
    • 点击“创建并继续”
    • 跳过角色分配 → 点击“完成”
  5. 下载 JSON 密钥：
    • 点击您的服务账户
    • 前往“密钥”标签 → “添加密钥” → “创建新密钥”
    • 选择“JSON” → 点击“创建”
    • 保存 JSON 文件 —— 您将需要其路径

将服务账户添加到搜索控制台

  1. 获取服务账户电子邮件：
    • 打开 JSON 文件
    • 查找 client_email 字段
    • 复制电子邮件（格式：gsc-mcp-server@your-project.iam.gserviceaccount.com）
  2. 添加到搜索控制台：
    • 转到 Google 搜索控制台
    • 选择您的属性
    • 点击“设置”（齿轮图标）
    • 点击“用户和权限”
    • 点击“添加用户”
    • 粘贴服务账户电子邮件
    • 选择“完全”权限
    • 点击“添加”

查找您的搜索控制台属性

  1. 在 Google 搜索控制台 中，选择您的属性
  2. 属性 URL 的格式如下：
    • 对于域名属性：sc-domain:example.com
    • 对于 URL 前缀属性：https://example.com/

测试您的设置（可选）

验证您的凭证：

pip install google-api-python-client

创建测试脚本（test_gsc.py）：

import os
from google.oauth2 import service_account
from googleapiclient.discovery import build

# 设置凭证路径
os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = "/path/to/your/service-account-key.json"

# 测试连接
credentials = service_account.Credentials.from_service_account_file(
    os.environ["GOOGLE_APPLICATION_CREDENTIALS"],
    scopes=['https://www.googleapis.com/auth/webmasters.readonly']
)

service = build('searchconsole', 'v1', credentials=
credentials)
print("✅ GSC 凭证工作正常！")

运行测试：

python test_gsc.py

如果您看到“✅ GSC 凭证工作正常！”则可以继续进行。

第二步：安装 MCP 服务器

选择一种方法：

方法 A：pip 安装（推荐）

pip install google-search-console-mcp

MCP 配置：

首先，检查您的 Python 命令：

python3 --version
python --version

然后使用适当的配置：

如果 python3 --version 工作正常：

{
  "mcpServers": {
    "gsc-search": {
      "command": "python3",
      "args": ["-m", "gsc_mcp_server"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json",
        "GSC_SITE_URL": "https://example.com/"
      }
    }
  }
}

如果 python --version 工作正常：

{
  "mcpServers": {
    "gsc-search": {
      "command": "python",
      "args": ["-m", "gsc_mcp_server"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json",
        "GSC_SITE_URL": "https://example.com/"
      }
    }
  }
}

方法 B：GitHub 下载

git clone https://github.com/surendranb/google-search-console-mcp.git
cd google-search-console-mcp
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

MCP 配置：

{
  "mcpServers": {
    "gsc-search": {
      "command": "/full/path/to/google-search-console-mcp/venv/bin/python",
      "args": ["/full/path/to/google-search-console-mcp/gsc_mcp_server.py"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/service-account-key.json",
        "GSC_SITE_URL": "https://example.com/"
      }
    }
  }
}

第三步：更新配置

替换您 MCP 配置中的这些占位符：

  • /path/to/your/service-account-key.json 替换为您 JSON 文件的路径
  • https://example.com/ 替换为您的搜索控制台属性 URL
  • /full/path/to/google-search-console-mcp/ 替换为您下载的路径（仅限方法 B）

重要提示：

  • 对于 URL 前缀属性：使用 https://example.com/ 格式
  • 对于域名属性：使用 sc-domain:example.com 格式
  • 确保 URL 格式与您的搜索控制台属性完全匹配

使用方法

一旦配置好，您可以向您的 MCP 客户端提问如下问题：

搜索性能分析

  • 我的网站过去一周的搜索性能如何？
  • 显示上个月按国家划分的点击次数和展示次数
  • 比较不同日期范围的点击率

关键词分析

  • 我的顶级关键词是什么，按点击次数排序？
  • 显示每个查询和设备类型的平均位置
  • 分析查询类型下的搜索外观

页面性能

  • 我的顶级页面是什么，按展示次数排序？
  • 显示每个页面和设备类型的点击率
  • 分析内容类型下的搜索性能

多维度分析

  • 显示按国家和设备划分的点击次数和展示次数
  • 分析查询和页面下的搜索性能
  • 比较不同搜索外观下的性能

快速开始示例

尝试这些示例查询以查看 MCP 的分析能力：

1. 地理分布

显示过去 30 天内按国家划分的搜索展示次数的地图，并按点击次数与展示次数细分

这演示了：

  • 地理分析
  • 性能指标
  • 时间过滤
  • 数据可视化

2. 关键词性能

比较过去 90 天内每个查询和设备类型的平均位置和点击率

这演示了：

  • 多维度分析
  • 时间序列比较
  • 搜索指标
  • 设备细分

3. 页面性能

显示每个页面的点击次数和展示次数，比较最近 30 天与前 30 天

这演示了：

  • 内容分析
  • 时期对比
  • 性能跟踪
  • 页面归属

4. 搜索外观

我的顶级 10 个搜索外观是什么，按点击率排序，它们的性能在过去 3 个月内有何变化？

这演示了：

  • 功能分析
  • 趋势分析
  • 性能指标
  • 排序和排名

可用工具

该服务器提供 7 个主要工具：

  1. list_gsc_sites - 列出您搜索控制台中的所有已验证站点
  2. list_available_dimensions - 显示所有可用的 GSC 维度
  3. list_available_metrics - 显示所有可用的 GSC 指标
  4. get_search_analytics - 获取具有自定义筛选器的搜索性能数据
  5. get_sitemaps - 列出您网站提交的所有网站地图
  6. submit_sitemap - 向搜索控制台提交新的网站地图
  7. delete_sitemap - 从搜索控制台删除网站地图

维度和指标

访问所有 GSC 维度和指标：

可用维度

  • country：三位字母 ISO 3166-1 alpha-3 国家代码
  • device：DESKTOP、MOBILE 或 TABLET
  • page：页面的规范 URL
  • query：搜索查询字符串
  • searchAppearance：类型如 AMP_BLUE_LINK、RICHCARD、FEATURED_SNIPPET
  • date：YYYY-MM-DD 格式的日期

可用指标（始终返回）

  • clicks：总点击次数
  • impressions：总展示次数
  • ctr：百分比形式的点击率
  • position：平均搜索位置

故障排除

如果您遇到“没有名为 gsc_mcp_server 的模块”错误（方法 A）：

pip3 install --user google-search-console-mcp

如果您遇到“找不到可执行文件”错误：

  • 尝试另一个 Python 命令（python vs python3）
  • 如果需要，使用 pip3 而不是 pip

权限错误：

# 尝试用户安装而不是系统范围安装
pip install --user google-search-console-mcp

凭证不起作用：

  1. 验证 JSON 文件路径是否正确且可访问
  2. 检查服务账户权限：
    • 转到 Google Cloud 控制台 → IAM 和管理 → IAM
    • 查找您的服务账户 → 检查权限
  3. 验证搜索控制台访问权限：
    • 搜索控制台 → 设置 → 用户和权限
    • 检查是否有您的服务账户电子邮件
  4. 验证属性格式：
    • 域名属性：sc-domain:example.com ✅
    • URL 前缀属性：https://example.com/ ✅

API 配额/速率限制错误：

  • 搜索控制台每天有配额和速率限制
  • 尝试减少查询中的日期范围
  • 在大型请求之间等待几分钟

项目结构

google-search-console-mcp/
├── gsc_mcp_server.py       # 主 MCP 服务器
├── gsc_dimensions.json     # GSC 维度配置
├── gsc_metrics.json        # GSC 指标配置
├── g
sc_filters.json        # GSC 筛选器配置
├── requirements.txt        # Python 依赖项
├── pyproject.toml          # 包配置
├── README.md              # 文档
├── claude-config-template.json  # MCP 配置模板
└── logo.svg               # 项目标志

许可证

MIT 许可证