内容
# mcp-google-gsc
MCP 服务器，用于谷歌搜索控制台 -- 通过 Claude 实现搜索分析、网址检查和网站管理。
## 功能
- **搜索分析** -- 查询点击量、展示次数、点击率和排名，并支持灵活的维度过滤（查询、页面、设备、国家、日期）
- **网址检查** -- 检查任何网址的索引状态、移动设备可用性和丰富结果
- **网站列表** -- 列出您身份验证的账户（OAuth 用户或服务账户）可访问的所有已验证的搜索控制台属性
- **多客户端支持** -- 通过每个目录的配置文件映射管理多个 GSC 属性
## 安装
### 从 npm
```bash
npm install mcp-google-gsc
```
### 从源码
```bash
git clone https://github.com/mharnett/mcp-search-console.git
cd mcp-google-gsc
npm install
npm run build
```
## 配置
**安全：** 永远不要分享您的 `.mcp.json` 文件或将其提交到 git -- 它可能包含 API 凭证。 将 `.mcp.json` 添加到您的 `.gitignore` 中。
mcp-gsc 支持 **两种身份验证模式**。请选择适合您的设置。两种模式都不需要在硬编码的机器本地路径上放置任何文件 -- 凭证来自环境变量（或您创建的 `config.json`）。
**选择哪种模式：**
- **服务账户（模式 B）-- 推荐用于无人值守 / 服务器 / 无头使用。** 服务账户没有交互式登录过期或重新授权，因此它是适合始终在线部署的正确选择。唯一的设置要求是服务账户的电子邮件必须被授予您要查询的每个搜索控制台属性的访问权限（参见模式 B）。
- **用户 OAuth（模式 A）-- 用于个人 / 交互式使用**，您想使用自己的谷歌登录授权。
**同时配置时的优先级：** 如果显式设置了服务账户密钥文件（`GOOGLE_APPLICATION_CREDENTIALS` 或 `config.json` 中的 `credentials_file`），则它 **优先** 于任何 OAuth 刷新令牌或存储的 OAuth 凭证。如果两者均未配置，则服务器在启动时将发出带有 onboarding 消息的响亮错误，而不是静默猜测 -- 没有机器本地默认值，也没有模式之间的静默运行时故障转移。
### 模式 A：用户 OAuth（使用您自己的谷歌账户）
如果您想使用自己的谷歌登录（具有搜索控制台访问权限的账户）授权，请使用此模式。适合个人 / 交互式使用。
1. 在谷歌云控制台中，创建一个 **OAuth 2.0 客户端 ID**，类型为 **桌面应用程序**，并启用 **搜索控制台 API**。（对于桌面应用程序，谷歌接受任何 `http://localhost` 回环重定向 -- 您不需要预先注册端口。）
2. 导出您的客户端凭证：
```bash
export GOOGLE_GSC_CLIENT_ID=...apps.googleusercontent.com
export GOOGLE_GSC_CLIENT_SECRET=...
```
3. 生成刷新令牌（打开您的浏览器，使用 PKCE + `access_type=offline`）：
```bash
node get-refresh-token.cjs
```
> 不要将此命令的标准输出重定向到共享日志 -- 它按设计将刷新令牌打印到标准输出。
4. 将打印的行复制到您的环境中：
```bash
export GOOGLE_GSC_REFRESH_TOKEN=...
```
服务器在运行时从环境中读取 `GOOGLE_GSC_CLIENT_ID`、`GOOGLE_GSC_CLIENT_SECRET` 和 `GOOGLE_GSC_REFRESH_TOKEN`。
或者，运行引导助手 `npx mcp-gsc-auth`，它执行相同的 PKCE OAuth 流，让您选择默认的搜索控制台属性，并将结果写入每个用户的凭证文件。
### 模式 B：服务账户（推荐用于无人值守 / 服务器使用）
在无人值守 / 服务器 / 始终在线的场景中使用此模式 -- 这是推荐的路径，当没有人类存在以完成或刷新交互式登录时。
1. 创建一个具有搜索控制台 API 访问权限的谷歌云 **服务账户**，并下载其 JSON 密钥文件。
2. **授予服务账户的电子邮件地址对您要查询的每个搜索控制台属性的访问权限**（将其添加为搜索控制台中的用户）。如果服务账户在属性上没有此授予，则它可以进行身份验证，但将看不到任何网站。
3. 通过环境变量指向服务器的密钥文件 **（无硬编码路径）**：
```bash
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/your/service-account-key.json
```
### OAuth 范围
两种模式都请求单个 **只读** 范围：`https://www.googleapis.com/auth/webmasters.readonly`。所有四个工具都是只读的 -- 没有写入操作 -- 因此服务器永远不会请求读写访问权限。
范围在 `config.json` 中定义为 `oauth.scope`（参见 `config.example.json`）。OAuth 助手和运行时读取相同的值，因此它们永远不会漂移。如果 `config.json` 不存在（例如，新的安装），则使用提交的只读默认值。
### 多客户端配置（可选）
要将工作目录映射到搜索控制台属性，请在项目根目录中创建一个 `config.json`（参见 `config.example.json`）：
```json
{
"oauth": {
"scope": "https://www.googleapis.com/auth/webmasters.readonly"
},
"clients": {
"my-project": {
"name": "我的项目",
"folder": "/path/to/project",
"site_url": "https://example.com/"
}
}
}
```
## 使用
将以下内容添加到您的 Claude Code `.mcp.json` 中：
```json
{
"mcpServers": {
"gsc": {
"command": "node",
"args": ["/path/to/mcp-gsc/dist/index.js"]
}
}
}
```
或者，如果已全局安装：
```json
{
"mcpServers": {
"gsc": {
"command": "npx",
"args": ["mcp-google-gsc"]
}
}
}
```
**Claude 桌面版：** 将以下内容添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）。
## 工具
| 工具 | 描述 |
|------|-------------|
| `gsc_get_client_context` | 根据配置文件映射检测 GSC 属性 |
| `gsc_list_sites` | 列出身份验证账户可访问的所有已验证的搜索控制台属性 |
| `gsc_search_analytics` | 查询搜索性能数据（点击量、展示次数、点击率、排名），支持维度过滤 |
| `gsc_inspection` | 检查网址的索引状态、移动设备可用性和丰富结果 |
### gsc_search_analytics
支持维度：`query`、`page`、`device`、`country`、`date`。通过 `equals`、`contains`、`notContains` 等运算符过滤。日期范围默认为最近 28 天。
### gsc_inspection
返回特定网址在属性内的索引覆盖率、爬虫状态、移动设备可用性判决和丰富结果详情。
## 架构
- **弹性** -- 对所有谷歌 API 调用使用 cockatiel 实现重试、指数退避和电路中断模式
- **日志记录** -- 使用 pino 实现结构化日志记录，支持可配置的日志级别
- **响应处理** -- 响应被截断为 200KB 以保持在 MCP 传输限制内
## 许可证
MIT -- 请参阅 [LICENSE](LICENSE)。
---
由 Mark Harnett / [drak-marketing](https://github.com/drak-marketing) 构建
