Google Search Console Mcp Server

GSC-MCP-Server

Google Search Console MCP 服务 — 将 Google Search Console 连接到 Claude、Cursor 和其他 MCP 客户端。

功能

• 🔍 搜索分析 — 查询点击次数、展示次数、CTR 和排名数据
• 📊 SEO 机会 — 查找低 CTR 关键词，检测关键词蚕食问题
• 📈 报告 — 每周摘要、周期对比
• 🗺️ 站点地图 — 列出、提交和管理站点地图
• 🔎 URL 检查 — 检查索引状态（需要完整权限范围）
• 💾 缓存 — 使用 SQLite 缓存加快重复查询
• 🔐 安全 — OAuth 令牌存储在操作系统密钥链中

快速开始

# Install globally
npm install -g @appsyogi/gsc-mcp-server

# Set up OAuth credentials
gsc-mcp init

# Verify setup
gsc-mcp doctor

# Start the server (for MCP clients)
gsc-mcp run

前提条件

1. 创建 Google Cloud OAuth 凭据

你需要在 Google Cloud Console 中创建自己的 OAuth 凭据：

1. 前往 Google Cloud Console
2. 创建新项目或选择现有项目
3. 启用 Google Search Console API：
   • 前往“APIs & Services”→“Library”
   • 搜索“Google Search Console API”
   • 点击“Enable”
4. 创建 OAuth 凭据：
   • 前往“APIs & Services”→“Credentials”
   • 点击“Create Credentials”→“OAuth client ID”
   • 选择“Desktop application”
   • 为其命名（例如“GSC-MCP”）
   • 点击“Create”
5. 复制 Client ID 和 Client Secret
6. 添加测试用户（应用处于测试模式时必须执行此操作）：
   • 前往“APIs & Services”→“OAuth consent screen”
   • 滚动到“Test users”部分
   • 点击“Add users”
   • 添加你用于身份验证的 Google 账号邮箱地址
   • 点击“Save”

注意： 当应用的发布状态为“Testing”时，只有测试用户才能进行身份验证。你最多可以添加 100 个测试用户。

2. 配置 GSC-MCP

运行初始化命令并输入凭据：

gsc-mcp init

此操作将：

• 提示你输入 Client ID 和 Client Secret
• 打开浏览器进行 Google 身份验证
• 将刷新令牌安全地存储在操作系统密钥链中

使用方法

CLI 命令

# Initialize with OAuth (interactive)
gsc-mcp init

# Initialize with service account
gsc-mcp init --service-account /path/to/key.json

# Initialize with full scope (for sitemap submission, URL inspection)
gsc-mcp init --scope full

# Check configuration and connectivity
gsc-mcp doctor
gsc-mcp doctor --verbose

# Start MCP server (stdio mode)
gsc-mcp run

# Start in HTTP mode (for debugging)
gsc-mcp run --http 3333

# View current configuration
gsc-mcp config

# Clear credentials
gsc-mcp logout

MCP 客户端配置

Claude Desktop

将以下内容添加到 Claude Desktop 配置文件（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "gsc": {
      "command": "gsc-mcp",
      "args": ["run"]
    }
  }
}

VS Code（Copilot）

将以下内容添加到 VS Code MCP 设置（~/.vscode/mcp.json 或工作区设置）：

{
  "servers": {
    "gsc": {
      "command": "gsc-mcp",
      "args": ["run"],
      "type": "stdio"
    }
  }
}

Cursor

将以下内容添加到 Cursor MCP 配置中：

{
  "mcpServers": {
    "gsc": {
      "command": "npx",
      "args": ["-y", "@appsyogi/gsc-mcp-server", "run"]
    }
  }
}

可用工具

搜索分析

工具	描述
searchanalytics.query	使用维度和筛选条件查询搜索效果数据
report.comparePeriods	对比两个时间段

站点地图

工具	描述	权限范围
sitemaps.list	列出所有站点地图	readonly
sitemaps.get	获取站点地图详情	readonly
sitemaps.submit	提交站点地图	full
sitemaps.delete	删除站点地图	full

URL 检查

工具	描述	权限范围
urlInspection.inspect	检查 URL 的索引状态	full
urlInspection.batchInspect	检查多个 URL	full

SEO 机会

工具	描述
opportunities.lowCtrHighPos	查找可快速提升的关键词（排名 4-20，CTR 低）
opportunities.cannibalization	检测关键词蚕食
report.weeklySummary	生成每周效果摘要

导出

工具	描述
export.csv	将数据导出为 CSV
export.json	将数据导出为 JSON

LLM 优化（v0.2.0+）

所有工具都支持用于减少大模型使用场景下 Token 消耗的参数：

紧凑响应格式

为任意工具添加 format: "compact"，即可获得针对大模型优化的输出：

{
  "siteUrl": "sc-domain:example.com",
  "startDate": "2026-01-01",
  "endDate": "2026-01-28",
  "dimensions": ["query"],
  "format": "compact"
}

紧凑格式特性：

• 使用较短的键名（用 imp 代替 impressions，用 pos 代替 position）
• CTR 使用百分比字符串（"5.41%"，而非 0.054123...）
• 包含自然语言摘要字段
• 从页面路径中移除 URL 前缀

紧凑响应示例：

{
  "summary": "Top query 'example keyword' got 150 clicks at position 3.2",
  "rows": [
    {"key": "example keyword", "clicks": 150, "imp": 2800, "ctr": "5.36%", "pos": 3.2}
  ]
}

日期汇总粒度

对于日期维度查询，可使用 granularity 减少行数：

{
  "siteUrl": "sc-domain:example.com",
  "startDate": "2025-07-01",
  "endDate": "2026-01-28",
  "dimensions": ["date"],
  "granularity": "weekly"
}

选项：

• daily — 默认值，返回每日数据
• weekly — 按周汇总（以周一为每周起始日）
• monthly — 按月汇总
• auto — 根据日期范围自动选择（>90 天 = 按月，>21 天 = 按周）

默认行数限制

默认 rowLimit 为 25（针对大模型上下文窗口进行了优化）。需要时可使用更高的值：

{
  "siteUrl": "sc-domain:example.com",
  "rowLimit": 100
}

最大值：25,000 行。

资源

该服务提供可浏览的资源：

• gsc://sites — 列出所有媒体资源
• gsc://sites/{siteUrl}/sitemaps — 列出某个媒体资源的站点地图

权限范围

GSC-MCP 支持两个权限级别：

只读（默认）

• 搜索分析查询
• 列出站点地图
• SEO 分析工具

gsc-mcp init  # Uses readonly by default

完全权限

• 包含只读权限的所有功能，另外还包括：
• 提交/删除站点地图
• URL 检查

gsc-mcp init --scope full

配置文件

GSC-MCP 会将配置存储在特定于平台的位置：

平台	配置路径
macOS	~/.config/gsc-mcp/
Linux	~/.config/gsc-mcp/
Windows	%APPDATA%/gsc-mcp/

文件：

• config.json — OAuth 客户端 ID/密钥、权限范围设置
• cache.sqlite — 查询缓存和已保存的预设

如果系统密钥链可用，令牌会安全地存储在其中。

服务账号设置

对于自动化/服务端使用场景，可以使用服务账号代替 OAuth：

1. 在 Google Cloud Console 中创建服务账号
2. 下载 JSON 密钥文件
3. 在 Google Search Console 中将服务账号邮箱添加为所有者
4. 初始化：

gsc-mcp init --service-account /path/to/key.json

API 配额

Google Search Console API 的默认配额为每天 1,200 次查询。GSC-MCP 包含：

• 采用指数退避的自动重试
• 通过查询缓存减少 API 调用
• 处理大型结果集的分页

示例

查找快速见效的关键词

Use gsc-mcp to find quick-win opportunities for my site https://example.com

周报

Generate a weekly performance summary for https://example.com

对比时间段

Compare search performance for https://example.com between last week and the week before

导出数据

Export the top 1000 queries for https://example.com in the last 28 days as CSV

开发

# Clone the repo
git clone https://github.com/AppsYogi-com/gsc-mcp-server.git
cd gsc-mcp-server

# Install dependencies
npm install

# Build
npm run build

# Run in dev mode
npm run dev

# Test locally
node dist/cli/index.js doctor

许可证

MIT

参与贡献

欢迎贡献！请提交 issue 或 PR。

致谢

使用以下项目构建：

• @modelcontextprotocol/sdk
• googleapis
• commander
• better-sqlite3