内容
# gsc-mcp
[](https://pypi.org/project/gsc-mcp-tools/)
[](https://python.org)
[](https://github.com/FlorianBruniaux/google-search-console-mcp)
[](LICENSE)
谷歌搜索控制台MCP服务器，包含36种工具，涵盖搜索分析、网址检查、谷歌索引API、谷歌分析4、核心网页生命体征（CrUX）、站点地图审核和JSON-LD模式验证。基于Python 3.11+和FastMCP构建。
**TL;DR:** 使用`uvx gsc-mcp-tools`进行安装，指向您的GSC服务账户，并询问Claude诸如“我的网站上哪些页面被爬取但未被索引？提交它们。” 服务器处理谷歌API调用、批量处理、重试和配额跟踪。所有输出都是结构化的JSON，因此Claude可以在没有解析歧义的情况下跨结果进行推理。
## 功能
```
You → Claude → gsc-mcp
├── 属性列表 （列表、详情、功能）
├── 分析 （性能、周期、异常）
├── SEO （快速优化、流量下降、内部竞争）
├── 检查 （网址状态、批量、问题类别）
├── 索引API （提交网址、真实HTTP批量）
├── 站点地图 （列表、提交、审核覆盖率）
├── GA4 （页面、来源、实时、漏斗）
├── 跨GSC+GA4 （健康检查、页面分析）
├── CrUX （核心网页生命体征、历史）
└── 技术 （JSON-LD模式验证）
```
### 工具总结
| 类别 | 工具 | 功能 |
|---|---|---|
| 属性 | `list_properties`、`get_site_details`、`get_capabilities` | 发现和检查GSC属性 |
| 分析 | `get_search_analytics`、`get_performance_overview`、`compare_search_periods`、`get_search_by_page_query`、`get_advanced_search_analytics`、`analytics_anomalies` | 查询印象、点击量、CTR、排名；比较周期；检测异常 |
| SEO | `quick_wins`、`traffic_drops`、`seo_striking_distance`、`seo_cannibalization`、`seo_lost_queries`、`check_alerts` | 发现优化机会、诊断流量下降、检测内部竞争 |
| 检查 | `inspect_url`、`batch_url_inspection`、`check_indexing_issues` | 网址索引状态、爬取判决、规范、按问题类型分类 |
| 索引 | `submit_url`、`submit_batch` | 通过谷歌索引API请求（重新）索引，真实HTTP批量，配额跟踪 |
| 站点地图 | `list_sitemaps`、`submit_sitemap`、`sitemaps_get`、`sitemaps_delete`、`sitemap_audit` | 管理提交的站点地图；审核声明的网址与GSC覆盖率 |
| GA4 | `ga4_organic_landing_pages`、`ga4_traffic_sources`、`ga4_page_performance`、`ga4_realtime`、`ga4_user_behavior`、`ga4_conversion_funnel` | 分析4数据：会话、参与度、转化、实时（均可按`hostname`和`country`筛选） |
| 跨 | `traffic_health_check`、`page_analysis` | 结合GSC点击量与GA4会话，检测跟踪差距并按机会评分页面 |
| CrUX | `crux_page_vitals`、`crux_history` | 真实用户核心网页生命体征（LCP、INP、CLS、FCP、TTFB），来自Chrome UX Report API，需要`CRUX_API_KEY` |
| 技术 | `schema_validate` | 获取任何公开网址并验证其JSON-LD结构化数据模式；建议按网址模式缺失模式 |
## 为什么存在
两个优秀的开源项目涵盖了部分问题：
**[AminForou/mcp-gsc](https://github.com/AminForou/mcp-gsc)** （Python，1k+星）具有优秀的搜索分析、丰富的SEO工具和可靠的OAuth + 服务账户认证。它不包括谷歌索引API（无`submit_url`，无`submit_batch`）。您可以分析流量但无法请求重新索引。
**[Suganthan-Mohanadasan/Suganthans-GSC-MCP](https://github.com/Suganthan-Mohanadasan/Suganthans-GSC-MCP)** （Node.js/TypeScript）添加了索引API，但其`submit_batch`是一个顺序`for`循环，延迟100毫秒，不是真正的HTTP批量。同时，它混合了纯文本和JSON输出，硬编码版本号与package.json不符，且无重试逻辑。
该项目取自第一个项目的认证模式和SEO工具，第二个项目的索引API范围，并修复了两个项目的空白。
### 为什么选择Python而不是Go或Rust
谷歌API Python客户端（`google-api-python-client`）是这些API的官方、维护最好的客户端。它原生支持`service.new_batch_http_request()`，这是实现真正的HTTP多部分批量处理的关键，而无需手动实现线路格式。Go和Rust的谷歌API生态系统依赖于非官方或自动生成的客户端，不提供此方法。FastMCP也对Python有首选支持，几乎没有样板代码。权衡是启动延迟（几百毫秒vs编译二进制的近乎零延迟），但对于Claude交互调用的本地MCP服务器，这种权衡无关紧要。
### 与两个灵感项目相比有什么变化
| 功能 | AminForou/mcp-gsc | Suganthan | gsc-mcp |
|---|---|---|---|
| 谷歌索引API | 否 | 是（假批量） | 是（真实HTTP批量） |
| `submit_batch` | 不适用 | 顺序循环 | `new_batch_http_request()`，100/块 |
|令牌存储 | pickle | pickle | JSON（`creds.to_json()`） |
| 重试429/5xx | 否 | 否 | 是，指数级回退 |
| 配额跟踪 | 否 | 否 | 是，在180/200时警告 |
| 输出格式 | 混合文本+JSON | 混合 | 100% JSON + `_meta`块 |
## 工具（36）
| 类别 | 工具 | 描述 |
|---|---|---|
| 元数据 | `get_capabilities` | 列出所有可用工具 |
| 属性 | `list_properties` | 列出所有GSC属性 |
| 属性 | `get_site_details` | 获取特定属性的详细信息 |
| 分析 | `get_search_analytics` | 查询搜索性能数据 |
| 分析 | `get_performance_overview` | 总计 + 顶部查询 |
| 分析 | `compare_search_periods` | 比较两个连续周期 |
| 分析 | `get_search_by_page_query` | 按页面和查询划分的性能 |
| 分析 | `get_advanced_search_analytics` | 灵活的查询，自定义维度 和筛选器 |
| 分析 | `analytics_anomalies` | 每日点击量的Z分数异常检测 |
| SEO | `quick_wins` | 位置4-15中CTR低于基准的页面 |
| SEO | `traffic_drops` | 点击量下降的查询，附诊断 |
| SEO | `check_alerts` | 流量集中风险和排名机会 |
| SEO | `seo_striking_distance` | 位置8-15的查询，一步之遥即可进入第1页 |
| SEO | `seo_cannibalization` | 查询跨多个页面拆分（HHI冲突分数） |
| SEO | `seo_lost_queries` | 与上一周期相比，点击量下降>= 80%的查询 |
| 检查 | `inspect_url` | 通过URL检查API检查网址索引状态 |
| 检查 | `batch_url_inspection` | 一次检查最多10个网址 |
| 检查 | `check_indexing_issues` | 检查网址并按问题类型分类 |
| 索引 | `submit_url` | 请求单个网址的索引 |
| 索引 | `submit_batch` | 请求多个网址的索引（真实HTTP批量） |
| 站点地图 | `list_sitemaps` | 列出提交的站点地图 |
| 站点地图 | `submit_sitemap` | 提交站点地图网址 |
| 站点地图 | `sitemaps_get` | 获取单个站点地图的详细信息 |
| 站点地图 | `sitemaps_delete` | 删除提交的站点地图（附安全检查） |
| GA4 | `ga4_organic_landing_pages` | 有机着陆页面的会话和参与度 |
| GA4 | `ga4_traffic_sources` | 按渠道、来源和媒介划分的会话和转化 |
| GA4 | `ga4_page_performance` | 每个页面路径的7个指标，可选`CONTAINS`筛选 |
| GA4 | `ga4_realtime` | 当前活跃用户，按屏幕、国家和设备划分 |
| GA4 | `ga4_user_behavior` | 设备、国家和用户类型分解在一个批量调用中 |
| GA4 | `ga4_conversion_funnel` | 转化页面和事件计数，可选事件筛选 |
| 跨 | `traffic_health_check` | 检测跟踪差距的GA4 / GSC会话比率 |
| 跨 | `page_analysis` | GSC + GA4页面连接，机会分数，优先级排序 |
## 要求
- Python 3.11+
- 谷歌云项目，启用以下API：谷歌搜索控制台API、网络搜索索引API、谷歌分析数据API
- 服务账户JSON密钥（推荐）或OAuth桌面凭证
- 对于索引API：服务账户必须在GSC属性上具有**所有者级**访问权限（完全访问权限不够）
- 索引API默认配额：每天200个请求
## 安装
```bash
uvx gsc-mcp-tools
```
或使用pip：
```bash
pip install gsc-mcp-tools
```
从源码运行：
```bash
git clone https://github.com/FlorianBruniaux/google-search-console-mcp
cd google-search-console-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
```
## 配置
**完整设置指南：** [docs/google-setup.md](docs/google-setup.md)涵盖创建谷歌云项目、启用API、创建服务账户、将其添加到GSC并具有正确的权限级别以及配置GA4。
**首次审计提示：** [docs/starter-prompt.md](docs/starter-prompt.md)包含现成的提示，用于进行完整的站点审计、5分钟健康检查、单个页面检查、重新索引工作流和仅GA4分析。
### 快速启动（服务账户）
```bash
export GSC_SERVICE_ACCOUNT_PATH=/absolute/path/to/service-account.json
export GSC_SKIP_OAUTH=true
export GA4_PROPERTY_ID=123456789 # only needed for GA4 tools
export CRUX_API_KEY=AIza... # only needed for crux_page_vitals, crux_history
gsc-mcp
```
`CRUX_API_KEY`是谷歌API密钥（不是服务账户），启用了**Chrome UX Report API**，在GCP控制台中单独启用。它与GSC身份验证分开，仅适用于CrUX工具。
### 克劳德桌面
添加到`~/Library/Application Support/Claude/claude_desktop_config.json`：
```json
{
"mcpServers": {
"gsc-mcp": {
"command": "uvx",
"args": ["gsc-mcp-tools"],
"env": {
"GSC_SERVICE_ACCOUNT_PATH": "/absolute/path/to/service-account.json",
"GSC_SKIP_OAUTH": "true",
"GA4_PROPERTY_ID": "123456789",
"CRUX_API_KEY": "AIza..."
}
}
}
}
```
如果您不使用GA4工具，请删除`GA4_PROPERTY_ID`。保存后重启Claude Desktop。
### 多属性支持
要查询不同的GA4属性，而无需更改配置，请直接向任何GA4或跨工具传递`property_id`：
```python
ga4_traffic_sources(property_id="443684366")
traffic_health_check(site="sc-domain:example.com", property_id="443684366")
```
## 开发
```bash
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest tests/ -v
```
222+测试，均模拟（无需真实的谷歌API调用）。
## 灵感来源
- [AminForou/mcp-gsc](https://github.com/AminForou/mcp-gsc)：认证模式、OAuth + 服务账户流程、SEO分析结构
- [Suganthan-Mohanadasan/Suganthans-GSC-MCP](https://github.com/Suganthan-Mohanadasan/Suganthans-GSC-MCP)：索引API范围、`with_meta()`输出模式
## 许可证
MIT
连接信息
猜你喜欢
暂无推荐服务器