内容
GSC SEO MCP
将 Google Search Console 连接到 Cursor、Claude 或 Gemini。 用简单的英语提问并获取真实的 SEO 数据。
[](https://www.npmjs.com/package/gsc-seo-mcp)
[](https://modelcontextprotocol.io/)
[](LICENSE)
---
## 您可以在设置完成后向 AI 提问的内容
```
显示我网站最大的 SEO 机会。
哪些页面正在失去点击量？
找出排名在 4-15 位的关键词，我可以将其提升到第 1 页。
在过去 90 天内，区分品牌和非品牌流量。
哪些页面的点击率与其排名位置不符？
检查这些网址并告诉我索引出现了什么问题。
为过去 28 天生成 Markdown SEO 报告。
```
---
## 设置
有两个部分：
1. **Google** — 授予 MCP 访问您的 Search Console 数据的权限
2. **您的 AI 应用** — 告诉 Cursor / Claude / Gemini 如何运行它
首先选择您的 Google 认证方式：
| | 服务账户 | OAuth |
|---|---|---|
| 最适合 | 代理机构，客户网站，团队 | 个人网站，您自己的账户 |
| 工作原理 | JSON 密钥文件，无浏览器登录 | 通过浏览器登录一次 |
| 推荐？ | 是，更适合 MCP | 也有效 |
---
## 第 1 部分 — Google 设置
### 步骤 1：创建 Google Cloud 项目
这只是一个用于 API 访问的容器。它不是您的网站。
1. 访问 [console.cloud.google.com](https://console.cloud.google.com/)
2. 点击顶部的项目下拉菜单 → **新建项目**
3. 命名为 `GSC SEO MCP` 并点击 **创建**
4. 确保在创建后在顶部下拉菜单中选中它
### 步骤 2：启用 Search Console API
1. 访问 **APIs & Services → Library**
2. 搜索 **Google Search Console API** → 点击它 → 点击 **启用**
3. 可选：也启用 **Indexing API**，如果您需要 `indexing_*` 工具（仅对 JobPosting/livestream 页面有用）
---
### 选项 A：服务账户（推荐）
#### 1. 创建服务账户
1. 访问 **IAM & Admin → Service Accounts**
2. 点击 **创建服务账户**
3. 名称：`gsc-seo-mcp` → 点击 **创建并继续**
4. 跳过角色分配 → 点击 **继续** → 点击 **完成**
5. 复制服务账户电子邮件地址 — 格式如下：
```
gsc-seo-mcp@your-project-id.iam.gserviceaccount.com
```
#### 2. 下载密钥文件
1. 点击您刚刚创建的服务账户
2. 进入 **Keys** 标签页 → **添加密钥 → 创建新密钥 → JSON → 创建**
3. Google 会下载一个 `.json` 文件 — 将其保存在安全的位置，例如：
- Mac/Linux：`/Users/your-name/keys/gsc-seo-mcp.json`
- Windows：`C:/Users/your-name/keys/gsc-seo-mcp.json`
不要将此文件提交到 GitHub。请像密码一样保护它。
#### 3. 将其添加到 Search Console
1. 打开 [search.google.com/search-console](https://search.google.com/search-console)
2. 选择您的属性
3. 进入 **设置 → 用户和权限 → 添加用户**
4. 粘贴服务账户电子邮件地址，设置为 **完全** 权限，点击 **添加**
您需要是属性所有者才能执行此操作。
#### 4. 您的 MCP 配置
```json
{
"mcpServers": {
"gsc-seo": {
"command": "npx",
"args": ["-y", "gsc-seo-mcp"],
"env": {
"GSC_AUTH_MODE": "service_account",
"GSC_KEY_FILE": "/绝对路径/to/gsc-seo-mcp.json",
"GSC_SITE_URL": "sc-domain:example.com"
}
}
}
}
```
Windows 路径提示 — 使用正斜杠或双反斜杠：
```json
"GSC_KEY_FILE": "C:/Users/your-name/keys/gsc-seo-mcp.json"
```
---
### 选项 B：OAuth（使用 Google 登录）
如果您想通过浏览器登录使用自己的 Google 账户，请使用此选项。
#### 1. 设置 OAuth 同意屏幕
1. 访问 **APIs & Services → OAuth 同意屏幕**
2. 选择 **外部**（适用于 Gmail 账户）→ 填写应用名称、电子邮件 → 保存
3. 如果应用处于测试模式，请在 **测试用户** 下添加您的 Gmail 账户
#### 2. 创建 OAuth 客户端
1. 访问 **APIs & Services → 凭证 → 创建凭证 → OAuth 客户端 ID**
2. 应用类型：**桌面应用** → 命名为 `GSC SEO MCP Desktop` → 点击 **创建**
3. 点击 **下载 JSON** — 保存如下：
- Mac/Linux：`/Users/your-name/keys/gsc-oauth-client.json`
- Windows：`C:/Users/your-name/keys/gsc-oauth-client.json`
#### 3. 您的 MCP 配置
```json
{
"mcpServers": "gsc-seo": "command":px",
"args": ["-y", "-seo-mcp"],
"env": {
"GSC_AUTH_MODE": "oauth",
"GSC_OAUTH_SECRETS_FILE": "/绝对路径/to/gsc-oauth-client.json",
"GSC_TOKEN_FILE": "/绝对路径/to/gsc-oauth-token.json",
"GSC_SITE_URL": "sc-domain:example.com"
}
}
}
}
```
`GSC_TOKEN_FILE` 是 MCP 在首次浏览器登录后保存登录令牌的位置。如果您省略它，则默认保存到 `~c-seo-m.json`。
#### 4. 首次运行
MCP 客户端，然后要求它运行 `server_health` 或 `list_properties`。浏览器窗口将打开 — 使用 Google 登录并授予访问权限。就这样，不需要重复登录。
如果 Google 显示“未验证的应用”警告，请点击 **高级 → 继续** — 这是您自己的 OAuth 应用，没问题。
第 2 部分 — 添加到您的 AI 应用
需要 Node.js 20+。[下载](https://nodejs.org/) 如果您没有它。
### Cursor
在项目文件夹中创建 `.cursor/mcp.json`（或使用全局 MCP 设置）：
```json
{
"mcpServers": {
"gsc-seo": {
"command": "npx",
"args": ["-y", "gsc-seo-mcp"],
"env": {
"GSC_AUTH_MODE": "service_account",
"GSC_KEY_FILE": "/绝对路径/to/service-account.json",
"GSC_SITE_URL": "sc-domain:example.com",
"GSC_BRAND_TERMS": "mybrand,mybrand.com"
}
}
}
}
```
### Claude Desktop
编辑 `claude_desktop_config.json`:
- Mac: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"gsc-seo": {
"command": "npx",
"args": ["-y", "gsc-seo-mcp"],
"env": {
"GSC_AUTH_MODE": "service_account",
"GSC_KEY_FILE": "/绝对路径/to/service-account.json",
"GSC_SITE_URL": "sc-domain:example.com"
}
}
}
}
```
保存后重启 Claude Desktop。
### Claude Code
在您的项目中创建 `.mcp.json`：
```json
{
"mcpServers": {
"gsc-seo": {
"command": "npx",
"args": ["-y", "gsc-seo-mcp"],
"env": {
"GSC_AUTH_MODE": "service_account",
"GSC_KEY_FILE": "/绝对路径/to/service-account.json",
"GSC_SITE_URL": "sc-domain:example.com"
}
}
}
}
```
或通过 CLI：
```bash
claude mcp add --transport stdio \
--env GSC_AUTH_MODE=service_account \
--env GSC_KEY_FILE=/绝对路径/to/service-account.json \
--env GSC_SITE_URL=sc-domain:example.com \
gsc-seo -- npx -y gsc-seo-mcp
```
### Gemini CLI
编辑 `~/.gemini/settings.json`（或项目中的 `.gemini/settings.json`）：
```json
{
"mcpServers": {
"gsc-seo": {
"command": "npx",
"args": ["-y", "gsc-seo-mcp"],
"env": {
"GSC_AUTH_MODE": "service_account",
"GSC_KEY_FILE": "/绝对路径/to/service-account.json",
"GSC_SITE_URL": "sc-domain:example.com"
},
"timeout": 120000,
"trust": false
}
}
}
```
---
## 属性 URL 格式
使用 Search Console 中的确切格式：
```
sc-domain:example.com ← 域名属性（推荐）
https://www.example.com/ ← URL 前缀属性（包括尾部斜杠）
```
---
## 所有配置变量
| 变量 | 必需 | 功能 |
|---|---|---|
| `GSC_SITE_URL` | 推荐 | 默认属性。例如：`sc-domain:example.com` |
| `GSC_SITE_URLS` | 可选 | 多站点仪表板的逗号分隔属性 |
| `GSC_AUTH_MODE` | 可选 | `service_account` 或 `oauth`。在可能的情况下自动检测 |
| `GSC_KEY_FILE` | 服务账户 | 服务账户 JSON 密钥的路径 |
| `GOOGLE_APPLICATION_CREDENTIALS` | 服务账户 | 替代路径变量 |
| `GSC_OAUTH_SECRETS_FILE` | OAuth | OAuth 客户端密钥 JSON 的路径 |
| `GSC_OAUTH_CLIENT_ID` | OAuth 替代 | 不使用密钥文件时的客户端 ID |
| `GSC_OAUTH_CLIENT_SECRET` | OAuth 替代 | 不使用密钥文件时的客户端密钥 |
| `GSC_TOKEN_FILE` | 可选 | 登录后保存 OAuth 令牌的位置 |
| `GSC_BRAND_TERMS` | 可选 | 用于 `brand_nonbrand_split` 的逗号分隔品牌术语 |
| `GSC_REPORT_DIR` | 可选 | Markdown 报告的文件夹。默认为 `./reports` |
| `GSC_DATA_STATE` | 可选 | `all`、`final` 或 `hourly_all`。默认为 `all` |
---
## 工具
### 核心
| 工具 | 功能 |
|---|---|
| `server_health` | 显示配置状态、认证模式和工具数量 |
| `list_properties` | 列出您有权访问的所有 Search Console 属性 |
| `get_site` | 获取单个属性的权限详细信息 |
| `add_site` | 将网站添加到您的账户 |
| `delete_site` | 从您的账户中删除网站 |
### 搜索分析
| 工具 | 功能 |
|---|---|
| `search_analytics` | 具有维度、过滤器、搜索类型和数据状态的完整查询 |
| `advanced_filter_query` | 拉取最多 50,000 行进行更深入的审核 |
| `top_queries` | 顶级查询，可选按页面过滤 |
| `top_pages` | 顶级页面，可选按查询过滤 |
| `performance_overview` | 网站快照，包含周期比较、每日趋势、设备 |
| `compare_periods` | 当前与上一个周期按页面、查询、国家或设备比较 |
| `dimension_breakdown` | 按单个维度分析性能 |
| `page_query_matrix` | 将页面映射到驱动它们的查询 |
### SEO 分析
| 工具 | 回答 |
|---|---|
| `quick_wins` | 哪些关键词足够接近，可以快速提升？ |
| `ctr_opportunities` | 哪些摘要在排名位置上表现不佳？ |
| `content_decay` | 哪些页面在多个周期内下降？ |
| `traffic_drop_diagnosis` | 流量下降是排名、点击率、需求、覆盖率还是混合因素？ |
| `cannibalization | 哪些查询竞争页面上？ |
| `brand_nonbrand_split` | 流量品牌流量，多少是非？ |
|_intent_breakdown` | 查询如何分布在商业、交易、导航和本地？ |
| `device_country_opportunities` | 哪些设备/国家/页面段的点击率或排名较弱？ |
| `long_tail_questions` | 哪些问题查询值得扩展内容？ |
| `page_refresh_priorities` | 哪些页面应该首先更新？ |
| `internal_link_opportunities` | 哪些强大的页面可以支持较弱的页面？ |
| `query_page_fit` | 一个页面排名靠什么，内容是否匹配？ |
| `title_meta_brief` | 哪些查询应该为标题/元刷新提供信息？ |
| `anomaly_alerts` | 哪些页面最近出现了异常损失？ |
### 索引、站点地图、URL
| 工具 | 功能 |
|---|---|
| `inspect_url` | 检查一个 URL 的索引状态、规范、爬取、覆盖率 |
| `batch_inspect_urls` | 检查多个 URL |
| `index_coverage_summary` | 汇总 URL 列表的检查结果 |
| `list_sitemaps` | 列出已提交的站点地图及其错误和索引计数 |
| `get_sitemap` | 获取一个站点地图的详细信息 |
| `submit_sitemap` | 提交或刷新站点地图 |
| `delete_sitemap` | 删除已提交的站点地图 |
| `indexing_publish_url` | 为符合条件的 URL 发送索引 API 通知 |
| `indexing_batch_publish` | 发送多个索引 API 通知 |
| `indexing_get_metadata` | 检查 URL 的最新索引 API 通知状态 |
### 报告
| 工具 | 功能 |
|---|---|
| `multi_site_dashboard` | 在一个视图中比较多个属性 |
| `generate_markdown_report` | 将 Markdown SEO 报告保存到磁盘 |
| `verify_claim` | 在向客户报告之前重新查询 GSC 以检查数字 |
---
## 故障排除
**我的 AI 应用中没有显示工具**
确保已安装 Node.js 20+。检查您的 MCP 配置是否确切使用 `npx -y gsc-seo-mcp`。所有文件路径必须为绝对路径（不能使用 `~/` 或相对路径）。
**服务账户显示没有属性**
您需要将服务账户电子邮件地址添加到 Search Console 中的 **设置 → 用户和权限**。
**URL 检查失败**
URL 必须属于 `GSC_SITE_URL` 中的属性。对于 URL 前缀属性，请使用带有协议和尾部斜杠的确切前缀。
**OAuth 未打开浏览器**
设置 `GSC_OAUTH_PORT=0` 以让其选择一个空闲端口。如果您在远程机器上，可以改为在本地运行。
---
## 数据说明
- 搜索分析行按点击量排序。API 有内部行限制，因此并非所有可能的行都包含在内。
- `GSC_DATA_STATE=all` 包括最新数据。使用 `final` 获取已完成的报告数字。
- URL 检查显示 Google 的索引状态，而不是实时爬取。
- 索引 API 仅适用于 JobPosting 和 BroadcastEvent 页面 — 它不是一个通用的索引快捷方式。
---
## 安全
- 永远不要将服务账户密钥、OAuth 机密或令牌文件提交到 Git。
- 如果您不需要写入工具，请使用只读 Search Console 权限。
- 在批准调用 `delete_site`、`delete_sitemap`、`submit_sitemap` 和 `indexing_publish_url` 之前，请仔细检查它们。
---
## 官方文档
- [创建 Google Cloud 项目](https://cloud.google.com/resource-manager/docs/creating-managing-projects)
- [启用 API](https://developers.google.com/workspace/guides/enable-apis)
- [创建凭证](https://developers.google.com/workspace/guides/create-credentials)
- [Search Console 用户和权限](https://support.google.com/webmasters/answer/7687615)
- [Search Analytics API](https://developers.google.com/webmaster-tools/v1/searchanalytics/query)
- [URL 检查 API](https://developers.google.com/webmaster-tools/v1/urlInspection.index/inspect)
- [索引 API](https://developers.google.com/search/apis/indexing-api/v3/using-api)
- [模型上下文协议](https://modelcontextprotocol.io/)
---
## 许可证
MIT。如果这为您节省了时间，请给仓库加星。
