内容
# gsc-mcp-server
[](https://www.npmjs.com/package/@jlnkrth/gsc-mcp-server)
谷歌搜索控制台的MCP服务器。查询搜索性能，列出属性，检查网址，以及从Cursor，Claude Desktop或任何MCP兼容客户端列出站点地图。
**npm:** [@jlnkrth/gsc-mcp-server](https://www.npmjs.com/package/@jlnkrth/gsc-mcp-server)
> 使用作用域包名`@jlnkrth/gsc-mcp-server`。npm上的非作用域名称`gsc-mcp-server`是不同的包。
## 快速开始
| 情况 | 认证 | 运行MCP服务器 |
|-----------|------|----------------|
| **克隆此仓库** （在项目文件夹内） | `npm run auth` | `npm start` |
| **从npm安装** （任何其他目录） | `npx -y -p @jlnkrth/gsc-mcp-server gsc-mcp-auth` | `npx -y @jlnkrth/gsc-mcp-server` |
在认证前设置`GOOGLE_CLIENT_ID`和`GOOGLE_CLIENT_SECRET`（参见[谷歌云设置](#谷歌云设置)）。
> **使用谷歌通行密钥登录？** 没问题 — 通行密钥仅在认证过程中用于在浏览器中登录谷歌。您仍然需要自己的GCP OAuth客户端ID和密钥。
## 工具
| 工具 | 描述 |
|------|-------------|
| `gsc_list_sites` | 列出您的谷歌账户可访问的搜索控制台属性 |
| `gsc_search_analytics` | 查询点击量、展示次数、点击率和位置，并附有维度过滤器 |
| `gsc_inspect_url` | 检查网址的索引状态、爬取状态和移动设备可用性 |
| `gsc_list_sitemaps` | 列出已提交的站点地图，附有状态、错误和索引计数 |
### `gsc_search_analytics` 过滤器
| 参数 | 描述 |
|-----------|-------------|
| `query_filter` | 简写：包含此字符串的查询 |
| `page_filter` | 简写：包含此字符串的页面网址 |
| `dimension_filters` | 完整的GSC过滤器对象（高级） |
## 先决条件
- **Node.js 18+**
- 一个启用了搜索控制台API的**谷歌云项目**
- 一个**OAuth 2.0桌面客户端** （客户端ID + 密钥）
- 一个具有您要查询的属性访问权限的谷歌账户
## 谷歌云设置
1. 前往[谷歌云控制台](https://console.cloud.google.com)。
2. 创建或选择一个项目。
3. 打开**APIs & Services → Library** 并启用**谷歌搜索控制台API**。
4. 打开**APIs & Services → OAuth consent screen** — 配置同意屏幕。如果应用处于**Testing** 模式，请在**Test users**下添加您的谷歌账户，否则登录将失败。
5. 打开**APIs & Services → Credentials → Create Credentials → OAuth client ID**。
6. 应用类型：**桌面应用**。
7. 添加 `http://localhost:3336/callback` 作为授权重定向URI（如果提示）。
8. 复制**客户端ID** 和 **客户端密钥**。
## 安装和认证
### 从npm
```bash
export GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GOOGLE_CLIENT_SECRET="your-client-secret"
npx -y -p @jlnkrth/gsc-mcp-server gsc-mcp-auth
```
### 从源码
```bash
git clone https://github.com/jlnkrth/gsc-mcp-server.git
cd gsc-mcp-server
npm install
cp .env.example .env
# 编辑.env文件并添加您的凭证，然后：
export $(grep -v '^#' .env | xargs)
npm run auth
```
认证流程会在端口 **3336** 上打开浏览器。令牌默认保存在 `~/.config/gsc-mcp/tokens.json` （可通过 `GSC_TOKEN_PATH` 重写）。
## MCP客户端配置
### Cursor
添加到 `~/.cursor/mcp.json` （与现有服务器合并）：
```json
{
"mcpServers": {
"google-search-console": {
"command": "npx",
"args": ["-y", "@jlnkrth/gsc-mcp-server"],
"env": {
"GOOGLE_CLIENT_ID": "YOUR_CLIENT_ID",
"GOOGLE_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
"GSC_TOKEN_PATH": "/Users/you/.config/gsc-mcp/tokens.json"
}
}
}
}
```
保持 `mcp.json` 私密 — 它包含您的OAuth客户端密钥。不要将其提交到git。
对于本地开发，请将 `command` 指向Node：
```json
{
"mcpServers": {
"google-search-console": {
"command": "node",
"args": ["/absolute/path/to/gsc-mcp-server/src/index.js"],
"env": {
"GOOGLE_CLIENT_ID": "YOUR_CLIENT_ID",
"GOOGLE_CLIENT_SECRET": "YOUR_CLIENT_SECRET"
}
}
}
}
```
参见 [examples/cursor-mcp.json](examples/cursor-mcp.json)。
### Claude Desktop
添加到 `~/Library/Application Support/Claude/claude_desktop_config.json` 在macOS上（参见 [examples/claude-desktop.json](examples/claude-desktop.json)).
更改MCP配置后，**完全退出并重启** 您的客户端，以便服务器重新加载令牌。
## 示例提示
连接后，您可以询问您的AI助手：
- "列出我的搜索控制台属性"
- "https://example.com/在过去28天内按点击量排名前20的查询是什么？"
- "显示我上周印象最多的博客页面" （使用 `page_filter`）
- "https://example.com/blog/my-post 是否已编入索引？"
- "列出sc-domain:example.com的站点地图"
## 环境变量
| 变量 | 必需 | 描述 |
|----------|----------|-------------|
| `GOOGLE_CLIENT_ID` | 是 | OAuth 2.0桌面客户端ID |
| `GOOGLE_CLIENT_SECRET` | 是 | OAuth 2.0桌面客户端密钥 |
| `GSC_TOKEN_PATH` | 否 | 令牌文件路径（默认： `~/.config/gsc-mcp/tokens.json`） |
| `GOOGLE_LOGIN_HINT` | 否 | 预填充OAuth浏览器登录中的电子邮件 |
## 故障排除
| 症状 | 修复方法 |
|---------|-----|
| `Not authenticated` | 运行 `npx -y -p @jlnkrth/gsc-mcp-server gsc-mcp-auth` （或 `npm run auth` 如果在克隆内部），然后重启您的MCP客户端 |
| `npx` 在克隆的仓库中失败 | 在另一个目录中使用 `npm run auth` / `npm start`，或从另一个目录运行 `npx` |
| 谷歌登录失败 / 访问被拒绝 | 如果OAuth应用处于Testing模式，请在GCP中将您的谷歌账户添加为测试用户 |
| 已保存的令牌中没有 `refresh_token` | 在[谷歌账户权限](https://myaccount.google.com/permissions)中撤销应用权限，然后重新运行认证 |
| 端口3336被占用 | 释放端口或停止冲突的进程，然后重新运行认证 |
| API调用中的 `403` / 权限被拒绝 | 确认登录的谷歌账户有权访问搜索控制台中的属性 |
| MCP客户端找不到 `npx` | 在您的配置中使用 `node` 和 `src/index.js` 的完整路径 |
| 通过通行密钥登录后谷歌OAuth失败 | `GOOGLE_CLIENT_ID` / `SECRET` 必须是实际的GCP值 — 而不是占位符。检查重定向URI `http://localhost:3336/callback` |
## 相关MCP服务器
- [谷歌分析MCP](https://github.com/googleanalytics/google-analytics-mcp) — 官方GA4服务器
- [DataForSEO MCP](https://github.com/dataforseo/mcp-server-typescript) — 官方DataForSEO服务器
## 贡献
参见 [CONTRIBUTING.md](CONTRIBUTING.md) 以了解本地开发、测试和发布。
## 许可证
MIT
