内容
<div align="center">
# 搜索控制台连接工具
**搜索控制台是为仪表盘设计的。而这款工具提供了一种对话式交互。**
通过 Claude、Cursor 或任何 MCP 客户端与你的 Google 搜索控制台进行交流。
一次登录，30 秒。*无需 Google 云项目，无需 API 密钥。令牌从未离开过你的机器。*
[](https://www.npmjs.com/package/search-console-mcp-server)
[](./LICENSE)
[](https://nodejs.org)
[文档](https://www.getpercy.io/search-console-mcp) · [npm](https://www.npmjs.com/package/search-console-mcp-server) · [报告问题](https://github.com/sudomichael/search-console-mcp/issues)
</div>
<!-- TODO(launch): hero GIF here — login → consent → "Connected." → asking Claude "which pages lost clicks this month?" -->
---
```
Google 搜索控制台
│
▼
search-console-mcp ← 在你的机器上运行，只读
│
▼
Claude / Cursor / 任意 MCP 客户端
│
▼
"为什么我的流量下降了？"
```
其他所有的搜索控制台 MCP 服务器都需要你创建一个 Google 云项目、启用 API，并处理服务账户 JSON 文件。而这款工具不需要：
```bash
npx search-console-mcp-server login
```
你的浏览器会打开，你使用 Google 登录即可。令牌由 Google 直接颁发给你的机器，并存储在 `~/.search-console-mcp/` 中 - 任何数据都不会通过其他人的服务器。
| | 这款服务器 | 典型的 GSC MCP 设置 |
| --- | --- | --- |
| 设置 | `npx … login`，登录，完成（~30 秒） | 创建 Google 云项目，启用 API，创建 OAuth 凭证，下载 JSON，配置到它 |
| 运行时 | Node - `npx`，无需安装 | Python + uv/venv |
| 是否可以修改站点数据？ | **不可能** - 构造只读范围 | 写入范围，默认禁用破坏性操作 |
| 分析 | 5 个内置（检查，蚕食，临界距离，流量下降，索引审计） | 自带提示 |
## 首次运行的预期
```
$ npx search-console-mcp-server login
打开浏览器登录 Google…
已连接。你的搜索控制台已就绪 - 令牌存储在
~/.search-console-mcp（仅限此机器）中。
```
这就是整个设置过程。无需克隆，无需 Google 云控制台，无需 JSON 文件。
---
## 使用感受
```
你： 哪些页面最接近第一页？
Claude： 三个真正的机会，按印象排名：
1. /pricing - “记分应用定价” 位于第 11.2 位，每月有
2,400 次印象，几乎没有点击。 一次排名组跳转价值约 90 次点击/月。 标题不包含
查询；从那里开始。
2. /templates/trivia - 位置 12.8，查询 “trivia scoreboard”，
1,100 次印象/月。 页面排名但没有 H2 匹配
意图。
3. /blog/keep-score-online - 位置 9.4，有些天已经是第一页。
它正在与 /features 争夺流量 - 运行
cannibalization_check 在修改它之前。
```
*（示例输出 - 形状和数字是工具从您真实数据返回的内容。）*
## 内置 SEO 分析工具
五个现成的分析工具作为 MCP 提示提供 - 支持它们的客户端中的斜杠命令。结果，而不是 API 调用：
| 提示 | 您得到的内容 |
| --- | --- |
| `seo_checkup` | 与上个月的趋势，最大变动者，以及 3 个值得做的改动 |
| `cannibalization_check` | 两个页面竞争的查询 - 哪个应该赢，以及如何修复 |
| `striking_distance` | 位于第 5-15 位的查询 - 您没有获得的最快的流量，以及每个页面的修复方法 |
| `traffic_drop` | 流量下降时，哪些页面/查询丢失，索引或未索引，最可能的原因 |
| `indexing_audit` | 网站地图状态 + 您的顶级页面的索引检查，提供纯语言修复 |
## 设置
**1. 登录（一次）：**
```bash
npx search-console-mcp-server login
```
**2. 添加到您的 MCP 客户端：**
Claude 代码：
```bash
claude mcp add gsc -- npx -y search-console-mcp-server
```
Claude 桌面版 / Cursor / 其他（`mcpServers` 配置）：
```json
{
"mcpServers": {
"gsc": { "command": "npx", "args": ["-y", "search-console-mcp-server"] }
}
}
```
**3. 提问：
- *"这个月哪些页面的点击量比上个月减少了？*"
- *"显示我的查询位于第 8-15 位，带有真实印象 - 哪个最接近第 1 页？*"
- *"https://mysite.com/pricing 是否已编入索引？如果不是，为什么？*"
- *"我获得多少 Google Discover 流量？*"
## 工具
| 工具 | 它做什么 |
| --- | --- |
| `list_properties` | 您的 GSC 属性（首先调用 - 提供确切的 `siteUrl` 值） |
| `query_search_analytics` | 按查询，页面，日期，国家，设备 - 过滤，分页和所有流量源（包括 Google Discover）的点击量/印象/CTR/位置 |
| `compare_periods` | 最大的变动者，为您计算：当前期间与上一个期间，每个页面或查询的差异，按变化排序 |
| `inspect_url` | Google 的索引状态，针对 URL：已编入索引或未编入索引，为什么，选择的规范，上次爬取 |
| `inspect_urls` | 相同，批量处理 - 每次索引审核最多 10 个 URL |
| `list_sitemaps` | 提交的网站地图状态 |
构造只读：此工具请求的 Google 范围（`webmasters.readonly`）**无法** 修改您的属性，提交网站地图或更改任何内容 - 不是“默认禁用”。
`compare_periods` 调用向您的模型提供的内容（模型从不进行日期算术）：
```json
{ "key": "https://example.com/pricing",
"current": { "clicks": 1040, "impressions": 20502, "position": 6.4 },
"previous": { "clicks": 1070, "impressions": 17176, "position": 5.8 },
"deltaClicks": -30, "deltaImpressions": 3326, "deltaPosition": 0.6 }
```
## 隐私
- **只读** Google 范围（`webmasters.readonly`）。
- 令牌存储在您机器上的 `~/.search-console-mcp/credentials.json` 中，权限为 `chmod 600`。`npx search-console-mcp-server logout` 会删除它们。
- 无需遥测，无需代理 - API 调用直接从您的机器到 Google。
- 优先使用您自己的 Google 云项目？设置 `SEARCH_CONSOLE_MCP_CLIENT_ID` / `SEARCH_CONSOLE_MCP_CLIENT_SECRET`，它会使用您的。
## 常见问题 / 故障排除
**如何在不创建 Google 凭证的情况下进行登录？**
CLI 附带了一个 Google “桌面应用”OAuth 客户端 - 与 `gcloud` 和 GitHub 的 CLI 使用的相同支持模型。您的令牌仍然由 Google 直接颁发到您的机器（PKCE + 本地主机回调）；它们从未触及我们的服务器。整个身份验证路径在 [`src/auth.ts`](src/auth.ts) 中，大约 200 行 - 阅读它。想要完全不共享任何内容？使用您自己的凭证设置 `SEARCH_CONSOLE_MCP_CLIENT_ID` / `SEARCH_CONSOLE_MCP_CLIENT_SECRET`。
**切换 Google 账户？**
再次运行 `npx search-console-mcp-server login` - Google 会显示账户选择器。
**在我的 MCP 客户端中出现“未登录”错误？**
请在客户端运行登录的同一用户账户下运行登录；凭证存储在 `~/.search-console-mcp/` 中。
**属性在 `list_properties` 中缺失。**
登录的 Google 账户需要至少对它在搜索控制台中具有“受限”访问权限。
**为什么昨天的数据缺失？**
Google 搜索控制台数据滞后约 2-3 天。这是 Google 的问题，而不是工具的问题。历史记录可追溯约 16 个月。
**撤销访问权限？**
`npx search-console-mcp-server logout` 删除本地令牌；[myaccount.google.com/permissions](https://myaccount.google.com/permissions) 撤销授予的权限。
## 开发
```bash
git clone https://github.com/sudomichael/search-console-mcp
cd search-console-mcp && npm install
npm run dev # 从源代码运行
npm run build # 打包到 dist/（10KB，无 googleapis 依赖）
```
整个身份验证路径在 [`src/auth.ts`](src/auth.ts) 中，大约 200 行。为了验证上述任何隐私声明，请阅读源代码。
---
### 寻找更主动的东西？
此 MCP 服务器帮助您 *调查* - 您提问，它回答。
一周后，您可能会注意到您一直在问相同的问题：*什么东西掉了下来？什么是最接近第一页的？应该修复什么？*
[**Percy**](https://www.getpercy.io) 是另一半：它每周自行检查您的搜索控制台，建立策略，发送电子邮件告诉您要更改的内容 - 然后重新检查实时页面并衡量是否有效。
在此处探索。在那里执行。相同的理念：真实数据，普通英语，无仪表盘。
---
MIT 许可。欢迎提出问题和拉取请求。由 [Percy](https://www.getpercy.io) 构建。
