Google Search Console

Google Search Console MCP

英语 · 意大利语

通过 Google Search Console API 提供 17 个只读工具，另附一份确定性的 白标 HTML 审计报告，代理机构可以将其署上自己的名称并发送给 客户，支持英语或意大利语。

无需凭据，即可根据已提交的合成数据重新生成该报告：

python scripts/render_sample_report.py --lang en --open

安装

Claude Code

/plugin marketplace add acamolese/google-search-console-mcp
/plugin install google-search-console@acamolese

该插件包含 MCP 服务、五个技能（每周检查、蚕食检查、索引审计、内容机会、白标客户审计），以及一个用于配置三项凭据的提示词。

Claude Desktop

从 最新版本 下载 google-search-console.mcpb 并打开。需要安装 uv。或者直接编辑配置文件：

{
  "mcpServers": {
    "google-search-console": {
      "command": "uvx",
      "args": ["mcp-google-search-console"],
      "env": {
        "GSC_CLIENT_ID": "...",
        "GSC_CLIENT_SECRET": "...",
        "GSC_REFRESH_TOKEN": "..."
      }
    }
  }
}

Cursor、Codex、Gemini CLI、Zed

任何 MCP 客户端都使用相同的三行配置：命令 uvx、参数 mcp-google-search-console，以及三个 GSC_* 环境变量。

# Codex
codex mcp add google-search-console -- uvx mcp-google-search-console

# Gemini CLI
gemini mcp add google-search-console uvx mcp-google-search-console

Docker

docker build -t mcp-gsc .
docker run --rm -p 127.0.0.1:8765:8765 \
  -e GSC_CLIENT_ID -e GSC_CLIENT_SECRET -e GSC_REFRESH_TOKEN \
  -v "$PWD/reports:/reports" mcp-gsc

容器通过 /mcp 提供可流式传输的 HTTP 服务。它本身不提供身份验证：请将其限制在回环地址上，或置于反向代理之后。

身份验证

OAuth 范围为 webmasters.readonly，没有其他权限。此服务中的任何工具都无法修改 Search Console 中的媒体资源、站点地图或任何其他内容。

凭据按以下顺序解析：

1. 如果设置了 GSC_AUTH_MODE，则使用该值（oauth、service_account、adc）
2. GSC_SERVICE_ACCOUNT_FILE 或 GSC_SERVICE_ACCOUNT_JSON
3. GSC_CLIENT_ID + GSC_CLIENT_SECRET + GSC_REFRESH_TOKEN
4. ~/.config/mcp-google-search-console/ 中的令牌文件
5. 应用默认凭据

OAuth，一次性设置

1. 在 Google Cloud Console 中启用 Google Search Console API，并创建一个类型为 桌面应用 的 OAuth 客户端。

2. 导出客户端，或将下载的 JSON 保存为 ~/.config/mcp-google-search-console/oauth_credentials.json：

   export GSC_CLIENT_ID="...apps.googleusercontent.com"
   export GSC_CLIENT_SECRET="..."
   uvx mcp-google-search-console auth
   

3. 浏览器流程会输出三行 export 命令，供无状态配置使用；同时还会将令牌保存到 ~/.config/mcp-google-search-console/token.json，权限设为 0600。

在无头设备上，请在笔记本电脑上运行 auth，然后复制这三个环境 变量。--no-browser 会打印 URL，而不是打开 URL，但仍需要本地重定向。

服务账号

在 Search Console 中授予服务账号邮箱对媒体资源的读取权限， 然后将服务指向密钥：

export GSC_SERVICE_ACCOUNT_FILE=/path/to/key.json
# or, for a container:
export GSC_SERVICE_ACCOUNT_JSON='{"type":"service_account",...}'

检查是否正常运行

uvx mcp-google-search-console doctor

输出当前使用的身份验证模式、令牌过期时间、账号可读取的媒体资源数量，以及每个工具应用的默认值。机密信息会被隐藏。如果无法解析任何配置，则以状态码 1 退出；这也是大多数“服务无法启动”问题的答案。

工具

工具	可回答的问题
gsc_sites	此账号可以读取哪些资源，以及其确切格式是什么
gsc_site_details	单个资源的权限级别和类型
gsc_query	Search Analytics 报告，包含筛选条件、维度和分页
gsc_performance_overview	与上一时段相比，网站的表现是上升还是下降
gsc_compare_periods	两个时段之间发生了哪些变化，按点击量变化排序
gsc_quick_wins	哪些查询排名已接近顶部，稍加推动就能带来成效
gsc_ctr_gaps	有排名却无人点击的网页
gsc_cannibalization	多个网页相互竞争的查询
gsc_traffic_drops	点击量下降的网页，以及每个网页的可能原因
gsc_content_decay	连续数月排名下滑的网页
gsc_alerts	今天有哪些显著变化值得发出通知
gsc_portfolio	一览所有资源，按表现最差的排在前面
gsc_indexing_issues	这些 URL 是否已编入索引；如果没有，原因是什么
gsc_inspect_url	单个网页的完整 URL 检查结果
gsc_sitemaps	Google 已知的站点地图，以及其中的错误和警告
gsc_doctor	已配置哪些内容，以及 API 是否能正常响应
gsc_audit	完整的 HTML 报告

三个提示词封装了需要反复执行的工作流：gsc_weekly_report、 gsc_indexing_audit、gsc_content_opportunities。

为什么选择此服务

	此服务	常见的 GSC MCP 服务
面向客户端的报告	独立完整的 HTML，支持英语或意大利语，可自定义品牌	无
分析	蚕食、CTR 差距、衰退、下降诊断，在服务端运行	原始行数据，由模型分析
阈值	根据资源规模调整	固定值，或没有阈值
日期	period="last_month"、days=28，由服务端解析	仅支持显式指定日期
数据新鲜度	默认使用 dataState=all，与 UI 一致	仅使用 final
身份验证	OAuth、服务账号、ADC	仅 OAuth
输出	默认使用 TSV，token 数约为美化后的 JSON 的三分之一	json.dumps(indent=2)
错误	Google 提供的原因及处理建议	仅有 HTTP 状态码
测试	280 多项测试，覆盖 mcp 两个主版本和三种操作系统	通常没有

报告自定义

颜色、徽标、报告名称、品牌词和阈值来自 JSON 文件。 传入 branding_path，或将文件放在 ~/.config/mcp-google-search-console/branding.json，即可在所有地方应用：

{
  "brand_name": "Your Agency",
  "logo": "logo.png",
  "brand_terms": ["clientbrand", "client brand"],
  "colors": { "primary": "#2b6cb0", "primary_dark": "#1a365d" },
  "thresholds": { "min_impressions": 200 }
}

本地徽标会以 base64 编码嵌入文档。只有当 allow_external_fonts 为 true 时，才会保留远程徽标，因为除此之外，报告可以保证完全不包含外部 URL：没有 CDN，没有字体服务，也没有任何会在客户端打开报告时向外发送请求的内容。

brand_terms 的重要性超乎表面。若不设置它，系统会将域名的第一个标签用作品牌；对于缩写、控股公司和自创名称而言，这并不准确，还会悄悄错误标记品牌词与非品牌词的划分。报告会说明何时使用了推测结果。

配额和限制

• 16 个月的每日数据。更早的数据无论付出什么代价都无法获取。
• 小时级数据：仅限最近 10 天。
• URL 检查：每分钟 600 次，每个资源每天 2,000 次。大型网站最容易触及此限制。
• Search Analytics：每个站点每分钟 1,200 次查询。响应会在内存中缓存 6 小时（检查结果缓存 1 小时）；no_cache=true 可绕过缓存。
• 行数：每次 API 调用最多 25,000 行。工具默认返回 100 行，上限为 1,000 行，可使用 start_row 分页；响应会报告上限，绝不会静默应用上限。

环境变量

变量	默认值	用途
GSC_CLIENT_ID、GSC_CLIENT_SECRET、GSC_REFRESH_TOKEN		无状态 OAuth
GSC_SERVICE_ACCOUNT_FILE、GSC_SERVICE_ACCOUNT_JSON		服务账号
GSC_AUTH_MODE	auto	强制使用 oauth、service_account 或 adc
GSC_REPORT_LANGUAGE	en	报告语言：en 或 it
GSC_DATA_STATE	all	all 包含今天的部分数据，final 不包含
GSC_CACHE_TTL_SECONDS	21600	响应缓存 TTL；0 表示禁用
GSC_INSPECT_CONCURRENCY	5	并行 URL 检查数
GSC_LOG_LEVEL	WARNING	日志，始终写入 stderr
MCP_TRANSPORT、MCP_HOST、MCP_PORT	stdio	传输方式

故障排除

spawn uvx ENOENT — 客户端无法在 PATH 中找到 uvx。GUI 应用不会继承 shell 的 PATH。请使用绝对路径：运行 which uvx 即可获取，通常是 /Users/you/.local/bin/uvx。

每次调用都出现 403 forbidden — 几乎总是资源属性格式有误。网域属性格式为 sc-domain:example.com；URL 前缀属性格式为 https://example.com/，末尾的斜杠不可省略。gsc_sites 会返回准确字符串。

401 invalid_grant — 刷新令牌已被撤销或过期。对于仍处于“测试”状态的 OAuth 应用，Google 会在七天后使刷新令牌过期；请发布应用，或重新运行 auth。

403 quotaExceeded — 当日的 URL Inspection 配额已用完。配额会在明天重置；不会继续重试。

小型网站的报告为空 — 检查响应元数据中的阈值。阈值会根据资源属性调整，但最低值（50 次展示、10 次点击）仍然适用。传入 thresholds 可调低阈值。

其他问题 — 运行 doctor，并在问题报告中附上其输出。

安全性

• 仅请求只读权限范围，且绝不会扩大范围。
• 令牌文件以原子方式写入，并设置 0600 权限。通过环境变量提供的凭据绝不会写入磁盘。
• gsc_doctor 会隐藏客户端 ID，且绝不会返回令牌。
• 无遥测、无分析，且不会向 Google API 以外的任何主机发出请求。

报告政策请参阅 SECURITY.md。

开发

uv venv && uv pip install -e ".[dev]"
ruff check src tests scripts && ruff format --check src tests scripts
pytest -q --cov=google_search_console_mcp
python scripts/sync_versions.py
python scripts/render_sample_report.py --lang it --open

测试绝不会访问网络。实时测试通过 -m live 启用，并需要设置 GSC_LIVE_TESTS=1 及提供凭据；它们绝不会在 CI 中运行。

发布流程请参阅 docs/RELEASING.md。代码中未涵盖的决策记录在 docs/DECISIONS.md 中。

许可证

MIT。Chart.js 4.5.1 随附于 src/google_search_console_mcp/static/，同样采用 MIT 许可证，其许可证文件也位于该目录中。