用途
这是一个基于 Google Search Console API 的 MCP（Model Context Protocol）服务器，主要用于 SEO 数据分析与审计。它提供 17 个只读工具，帮助用户从 Google Search Console 中提取数据、诊断问题并生成报告，同时可作为 Claude Code 插件、.mcpb 包或 Docker 容器运行。
主要能力
- 性能查询：读取 Google Search Console 中的搜索效果数据。
- 快速优化机会：识别可快速提升的查询和页面。
- 点击率缺口分析：发现高曝光但点击率低的查询。
- 关键词自相残杀检测：识别多个页面竞争同一关键词的情况。
- 流量下滑诊断：分析流量下降的原因。
- 索引状态检查：通过 URL Inspection 工具检查页面索引情况。
- 品牌化 HTML 审计报告：生成独立、自包含的 HTML SEO 审计报告，支持英文和意大利文，可自定义颜色、Logo、报告名称、品牌词和阈值。报告包含 30/60/90 天路线图，且不包含任何外部 URL（无 CDN、字体服务等），可安全交付给客户。
使用方式
集成方式
- Claude Code 插件：包含 MCP 服务器、五个技能（每周回顾、自相残杀检查、索引审计、内容机会、品牌化客户审计）以及三个凭据的配置提示。
- .mcpb 包：从最新发行版下载
google-search-console.mcpb并打开，需安装uv。 - 任意 MCP 客户端（Cursor、Codex、Gemini CLI、Zed 等）：配置命令
uvx、参数mcp-google-search-console以及三个GSC_*环境变量。 - Docker：容器在
/mcp上使用 streamable HTTP，自身无认证，需保持于回环地址或置于反向代理之后。
认证
OAuth 范围仅为 webmasters.readonly，任何工具都无法修改 Search Console 中的属性、站点地图或其他内容。凭据解析顺序：GSC_AUTH_MODE、GSC_SERVICE_ACCOUNT_FILE 或 GSC_SERVICE_ACCOUNT_JSON、GSC_CLIENT_ID + GSC_CLIENT_SECRET + GSC_REFRESH_TOKEN、~/.config/mcp-google-search-console/ 下的令牌文件、应用默认凭据。
支持 OAuth 桌面应用流程和服务账号。OAuth 流程会打印三个导出行，并将令牌存储于 ~/.config/mcp-google-search-console/token.json（权限 0600）。无头机器上可在笔记本上运行 auth 并复制三个环境变量。服务账号需在 Search Console 中授予其邮箱读取权限，并指向密钥文件。
报告自定义
通过 JSON 文件配置颜色、Logo、报告名称、品牌词和阈值。传入 branding_path，或放置于 ~/.config/mcp-google-search-console/branding.json 以全局应用。本地 Logo 会以 base64 编码嵌入文档；远程 Logo 仅在 allow_external_fonts 为 true 时保留，否则报告保证不包含任何外部 URL。brand_terms 尤为重要，若未设置，将使用域名第一段作为品牌，可能对缩写、控股公司和自创名称产生错误标注。
可用提示
三个提示封装了重复的工作流：gsc_weekly_report、gsc_indexing_audit、gsc_content_opportunities。
适用场景
- SEO 专家和机构进行网站性能监控与客户审计。
- 内容营销团队发现内容机会和点击率缺口。
- 网站管理员诊断流量下滑和索引问题。
- 需要生成品牌化、可交付客户的中文或意大利文 SEO 报告的场景。
限制
- 数据范围：最多 16 个月的每日数据，更早数据不可用；小时级数据仅限最近 10 天。
- 配额：URL Inspection 每分钟 600 次，每属性每天 2000 次；Search Analytics 每站点每分钟 1200 次查询。响应内存缓存 6 小时（检查为 1 小时），
no_cache=true可绕过。 - 行数：每次 API 调用最多 25,000 行，工具默认 100，上限 1000，支持
start_row分页，上限会在响应中报告，不会静默应用。 - 只读：无任何写入权限。
- Token 安全：令牌文件以 0600 权限原子写入；环境变量提供的凭据不会写入磁盘。
gsc_doctor会掩盖客户端 ID，绝不返回令牌。无遥测、无分析、除 Google API 外无任何主机请求。 - 测试：测试从不访问网络。实时测试位于
-m live后，需GSC_LIVE_TESTS=1和凭据，且不在 CI 中运行。
故障排除
- spawn uvx ENOENT：客户端在 PATH 中找不到 uvx。GUI 应用不继承 shell PATH。使用绝对路径，如
which uvx输出。 - 403 forbidden：几乎总是属性格式问题。域属性为
sc-domain:example.com；URL 前缀属性为https://example.com/，包含末尾斜杠。gsc_sites返回确切的字符串。 - 401 invalid_grant：刷新令牌被撤销或过期。Google 对仍处于“测试”状态的 OAuth 应用在七天后使刷新令牌过期；发布应用或重新运行
auth。 - 403 quotaExceeded：每日 URL Inspection 配额已用完，明天重置，无重试。
- 小型站点报告为空：检查响应元数据中的阈值。阈值会适应属性，但底线（50 次展示、10 次点击）仍适用。传入阈值可降低。
- 其他问题：运行
doctor并在问题中包含其输出。
其他信息
- 许可证：MIT。Chart.js 4.5.1 以 MIT 许可证内置在
src/google_search_console_mcp/static/下。 - 版本发布见
docs/RELEASING.md；代码未覆盖的决策记录在docs/DECISIONS.md。 - 安全策略见
SECURITY.md。
仓库地址：https://github.com/acamolese/google-search-console-mcp
