内容
<div align="center" width="100%">
<h2>🔍 gsc-mcp</h2>
<p>为您的AI助手提供读取 <a href="https://search.google.com/search-console">谷歌搜索控制台</a> 数据的权限，涵盖您拥有的所有网站。</p>
<a target="_blank" href="https://github.com/AkashRajpurohit/gsc-mcp/stargazers"><img src="https://img.shields.io/github/stars/AkashRajpurohit/gsc-mcp" /></a>
<a target="_blank" href="https://github.com/AkashRajpurohit/gsc-mcp/blob/main/LICENSE"><img src="https://img.shields.io/github/license/AkashRajpurohit/gsc-mcp" /></a>
<img alt="Node 版本" src="https://img.shields.io/badge/node-%3E%3D22.5-339933?logo=nodedotjs&logoColor=white" />
<img alt="MCP 服务器" src="https://img.shields.io/badge/MCP-server-1f1f1f" />
<img alt="访客" src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fvc.akashrajpurohit.com%2Fc%2Fakash~gh~gsc-mcp&query=count&style=flat&logo=github&label=访客&color=066da5" />
<a target="_blank" href="https://ko-fi.com/akashrajpurohit"><img src="https://img.shields.io/badge/Ko--fi-F16061?style=flat-square&logo=ko-fi&logoColor=white" /></a>
<a target="_blank" href="https://akashrajpurohit.com/sponsors/?ref=gsc-mcp"><img src="https://img.shields.io/badge/赞助-AkashRajpurohit-F16061?style=flat-square&logoColor=white" /></a>
<a target="_blank" href="https://twitter.com/akashwhocodes"><img alt="关注 Twitter" src="https://img.shields.io/twitter/follow/akashwhocodes.svg?style=social&label=@akashwhocodes" /></a>
<br />
<br />
<p align="center">
<a href="https://github.com/AkashRajpurohit/gsc-mcp/issues/new?template=bug_report.yml">报告错误</a>
·
<a href="https://github.com/AkashRajpurohit/gsc-mcp/issues/new?template=feature_request.yml">功能请求</a>
·
<a href="https://github.com/AkashRajpurohit?tab=repositories">更多项目</a>
</p>
</div>
<hr />
通常，查看网站在谷歌上的表现需要登录搜索控制台，选择一个网站，调整日期范围，然后查看图表。该工具连接您的助手（Claude Code、Claude Desktop、Cursor 或任何 MCP 客户端）直接连接到搜索控制台 API，这样您只需询问 — “这个月的热门查询是什么？”或“这个页面已索引了吗？” — 即可立即获得结果。
一个服务账户凭证可以涵盖 **所有** 您的网站，因此您可以在无需切换账户的情况下跨网站查询。而且由于该凭证是只读的，因此您的助手可以查看但不能修改。
## ✨ 功能
**它可以：**
- 列出凭证可以读取的每个搜索控制台网站。
- 拉取点击量、展示次数、点击率和平均位置 — 按查询、页面、日期、国家、设备或搜索外观分组。
- 检查任何 URL 的索引状态（已索引或未索引、最后爬取、规范、覆盖状态、移动可用性）。
- 显示您提交的站点地图及其索引与提交的计数。
**它不能：**
- **写入任何内容。** 凭证使用谷歌的只读搜索控制台范围，因此它无法提交站点地图、更改设置、添加或删除网站，或以任何方式修改您的账户。
- 跳过搜索控制台自己的数据限制。它看到的正是 API 公开的内容 — 相同的 ~16 个月窗口和采样谷歌提供给所有人。
- 将您的数据发送到除您的计算机和谷歌 API 之外的任何地方。中间没有第三方服务器。
## 📦 开始之前
您需要：
- 一个 **谷歌云项目** 和 `gcloud` CLI（或云控制台）来创建服务账户。
- 一个或多个 **已验证的谷歌搜索控制台网站**，您可以授予访问权限。
- **[Node.js](https://nodejs.org/) 22.5 或更新版本。**
- 一个支持 MCP 的助手（例如 [Claude Code](https://claude.com/claude-code)）。
## 🔑 获取凭证
服务器作为一个 **服务账户** 进行身份验证 — 一个具有自己电子邮件的机器人谷歌身份。您创建一个，授予每个网站的读取权限，然后它就可以读取所有网站。
### 1. 创建服务账户和密钥
```bash
gcloud config set project YOUR_PROJECT_ID
gcloud services enable searchconsole.googleapis.com
gcloud iam service-accounts create gsc-reader --display-name="GSC Reader"
mkdir -p ~/.config/gsc-mcp
gcloud iam service-accounts keys create ~/.config/gsc-mcp/key.json \
--iam-account=gsc-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com
```
这会将一个 JSON 密钥写入 `~/.config/gsc-mcp/key.json`。请保持私钥 — 它是一个凭证，而不是配置。（此存储库的 `.gitignore` 已经阻止了 `*key*.json`，因此您不会意外提交它。）
服务账户存在于一个云项目中，但其身份适用于您授予它的任何网站 — 项目选择无关紧要。
### 2. 在每个网站上授予权限
在 [搜索控制台](https://search.google.com/search-console) 中，打开每个网站 → **设置 → 用户和权限 → 添加用户**。添加服务账户电子邮件（`gsc-reader@YOUR_PROJECT_ID.iam.gserviceaccount.com`）并赋予 **受限**（读取）角色。
稍后添加新网站只需在此处再授予一次 — 无需更改代码或配置。
## 🚀 安装
```bash
git clone https://github.com/AkashRajpurohit/gsc-mcp.git
cd gsc-mcp
npm install
```
然后使用您的助手注册它。注意 `mcp.mjs` 的完整路径 — 您将在下面需要它：
```bash
echo "$PWD/mcp.mjs"
```
### Claude Code
```bash
claude mcp add gsc --scope user -- node "$PWD/mcp.mjs"
```
`--scope user` 将其注册到该机器上的每个 Claude Code 会话中。重启会话（或启动新会话）以获取工具。
### Claude Desktop
打开 **设置 → 开发者 → 编辑配置**（或直接编辑 `claude_desktop_config.json`）并添加：
```json
{
"mcpServers": {
"gsc": {
"command": "node",
"args": ["/绝对路径/到/gsc-mcp/mcp.mjs"]
}
}
}
```
重启 Claude Desktop。
### Cursor
打开 **设置 → MCP → 添加新的全局 MCP 服务器**（或编辑 `~/.cursor/mcp.json`）并添加与上述相同的 `gsc` 条目：
```json
{
"mcpServers": {
"gsc": {
"command": "node",
"args": ["/绝对路径/到/gsc-mcp/mcp.mjs"]
}
}
}
```
### Windsurf
编辑 `~/.codeium/windsurf/mcp_config.json` 并在 `mcpServers` 下添加相同的 `gsc` 条目。
### VS Code（GitHub Copilot）
将其添加到工作区中的 `.vscode/mcp.json`（或从命令面板运行 **MCP：添加服务器**）：
```json
{
"servers": {
"gsc": {
"command": "node",
"args": ["/绝对路径/到/gsc-mcp/mcp.mjs"]
}
}
}
```
> 如果您的密钥不在默认路径，请在上述任何条目中添加 `"env": { "GSC_KEY_PATH": "/绝对路径/到/key.json" }`。
### 任何其他 MCP 客户端
注册一个 **stdio** 服务器，该服务器运行 `node /绝对路径/到/gsc-mcp/mcp.mjs`。这就是服务器所需的一切。
注册后，启动新会话并要求您的助手“列出我的搜索控制台网站”。如果它返回您的网站，则您已准备就绪。
## 💬 如何使用
只需与您的助手交谈。例如：
- “列出我所有的搜索控制台网站。”
- “example.com 在过去 28 天内的前 20 个查询是什么？”
- “显示我这个月与上个月相比点击量下降的页面。”
- “哪些查询的展示次数高但点击率低？”
- “https://example.com/blog/my-post/ 是否被谷歌索引？”
- “我的站点地图提交了多少网址，索引了多少？”
在幕后，它提供了四个您的助手自动使用的工具：
| 工具 | 功能 |
|------|--------------|
| `gsc_list_sites` | 列出可读取的网站及其确切的 `siteUrl` 值。 |
| `gsc_search_analytics` | 按查询、页面、日期、国家、设备或搜索外观分组的点击量、展示次数、点击率和位置。 |
| `gsc_inspect_url` | 单个 URL 的索引状态（已索引、最后爬取、规范、覆盖范围）。 |
| `gsc_list_sitemaps` | 已提交与已索引的计数，每个站点地图的错误和警告。 |
每个工具都是 **只读** 的 — 底层凭证实际上无法更改您的任何数据。
## 🧪 在没有助手的情况下试用
有一个小的 CLI 封装了相同的核心，方便进行健全性检查：
```bash
node cli.mjs sites
node cli.mjs perf "sc-domain:example.com"
node cli.mjs pages "sc-domain:example.com"
node cli.mjs queries "sc-domain:example.com"
node cli.mjs inspect "sc-domain:example.com" "https://example.com/blog/my-post/"
node cli.mjs sitemaps "sc-domain:example.com"
```
域名属性类似于 `sc-domain:example.com`；URL 前缀属性类似于 `https://example.com/`。运行 `node cli.mjs sites` 以查看每个网站的确切 `siteUrl`。
## ⚙️ 配置
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `GSC_KEY_PATH` | `~/.config/gsc-mcp/key.json` | 服务账户 JSON 密钥的路径。 |
## 🏗️ 如何组合
```
MCP 客户端 ──stdio──▶ mcp.mjs ──▶ gsc.mjs ──▶ 谷歌搜索控制台 API
（工具） （身份验证 + 调用） （服务账户密钥）
```
- `gsc.mjs` — 谷歌 API 客户端。使用服务账户密钥进行身份验证并封装搜索控制台 API（网站、搜索分析、URL 检查、站点地图）。
- `mcp.mjs` — MCP 服务器（stdio 传输）向您的助手公开这些工具。
- `cli.mjs` — 相同的核心，可手动运行。
核心（`gsc.mjs`）是与传输无关的。要将此作为始终在线的远程 MCP 运行，而不是本地 stdio 进程，请将其容器化，通过身份验证代理以 HTTP/SSE 公开它，将密钥作为机密挂载，并使用您的客户端注册远程 URL — 只有托管发生变化。
## 🩺 如果它找不到您的网站
- **`gsc_list_sites` 返回空列表** — 服务账户尚未授予任何网站的权限。请重新检查步骤 2：您在搜索控制台中添加的电子邮件必须与您的密钥的 `client_email` 完全匹配。
- **身份验证或“文件未找到”错误** — 密钥不在服务器期望的位置。确认路径，或设置 `GSC_KEY_PATH` 以指向它。
- **特定网站 403 错误** — 该网站尚未与服务账户共享。在“用户和权限”下添加它。
## ⚖️ 许可和免责声明
**本项目与谷歌无任何关联、认可或关联。** 它是一个独立的开源工具，使用您创建和控制的凭证与谷歌公开的搜索控制台 API 进行通信。“谷歌搜索控制台”是谷歌 LLC 的商标，仅在此用于描述该工具的作用。
该工具在 MIT 许可下发布（参见 `LICENSE`）。它按原样提供，不提供任何保证。它仅使用谷歌的只读搜索控制台范围，因此它可以读取您的数据，但永远不能修改您的账户。
