gsc-mcp 是一个为 AI 助手设计的 MCP（模型上下文协议）服务器，将 Google Search Console 的数据和操作能力暴露给 AI 代理。其目标是将 SEO 中繁琐的部分——查找接近首页排名的关键词、检查索引状态、保持站点地图健康——自动化。该项目由 Conor Bronsdon 构建，最初用于两个网站（一个播客和一个个人网站）的 SEO，但并不特定于这些网站，可指向任何已验证的媒体资源。
用途方面：该 MCP 服务器提供搜索分析数据（按查询、页面、国家/地区、设备），计算临近首页的关键词（striking distance），管理站点地图，以及检查特定 URL 的索引状态。它旨在让 AI 助手能够访问有机搜索背后的数据和操作杠杆。
主要能力：提供 7 个工具，其中 5 个为只读工具，2 个为写入工具（gsc_submit_sitemap 和 gsc_delete_sitemap）。每个工具都带有 MCP 读写注释，客户端可以区分只读和写入工具。读取工具标记为 readOnlyHint: true；gsc_submit_sitemap 为非破坏性写入；gsc_delete_sitemap 标记为 destructiveHint: true。列表工具默认行数限制（row_limit/limit）为 25 以保持响应紧凑，因为代理按响应消耗令牌。支持派生视图如 gsc_striking_distance（客户端计算：拉取最多 1000 条查询行并过滤到位置区间）。支持列出已验证的媒体资源（gsc_list_sites）。
使用方式：服务器使用 OAuth 已安装应用凭据（保存的刷新令牌），而非服务账户或 API 密钥。它从 ~/.config/gws/searchconsole_credentials.json 读取凭据（可通过 GSC_CREDENTIALS_PATH 环境变量指定其他路径）。该文件格式为 google-auth 的 Credentials.to_json() 形状，包含 client_id、client_secret、refresh_token 和 scopes。服务器直接使用 fetch 向 Google 的令牌端点刷新短期访问令牌，不依赖重量级的 googleapis 库。
设置步骤：1. 在 Search Console 中验证媒体资源（推荐域属性，通过 DNS TXT 记录验证，覆盖 http/https 和所有子域；gsc_list_sites 会显示为 sc-domain:example.com 或 https://example.com/）。2. 生成凭据：在 Google Cloud Console 创建 OAuth 客户端（类型：桌面应用），下载 client_secret.json，启用 Search Console API，运行已安装应用 OAuth 流程并请求所需范围，保存凭据到 ~/.config/gws/searchconsole_credentials.json。读取工具需要 https://www.googleapis.com/auth/webmasters.readonly 范围；写入工具和 URL 检查需要完整的 https://www.googleapis.com/auth/webmasters 范围。如果凭据只有只读范围，读取工具可用，写入工具会返回清晰的“需重新生成完整范围”错误。3. 配置 MCP 客户端（如 .mcp.json 或 claude_desktop_config.json）。默认路径无需 env 块。
服务器在没有凭据时也能启动并响应 tools/list，便于 MCP 检查器内省，工具调用则返回设置指引。stdout 保留给 MCP 传输。
适用场景：SEO 自动化，如让 AI 助手列出 Search Console 属性、显示过去 28 天的 striking-distance 关键词、检查特定 URL 的索引状态、管理站点地图等。适用于需要将 SEO 工作融入 AI 代理工作流的用户。
限制：无请求索引工具（设计如此）：Search Console 的“请求索引”按钮没有公开 API，Google 的 Indexing API 仅支持 JobPosting 和 BroadcastEvent 页面，不适用于普通内容，因此普通页面的索引请求需在 UI 中手动点击；gsc_submit_sitemap 是受支持的 API 方式。数据滞后约 2-3 天，Search Analytics 非实时，日期范围应结束于几天前。searchAnalytics 每次调用有上限：row_limit 最大 1000（API 允许 25000 但需分页），大量拉取需分页。Striking distance 是客户端计算，基于点击量前 1000 条查询行，非完整长尾。URL 检查有速率限制且慢，Google 对 URL Inspection API 有较低的每日配额，每次调用可能需 1-2 秒，应检查特定 URL 而非循环整个站点地图。无属性添加/删除工具，需在 Search Console UI 中验证属性。通用 API 配额适用，HTTP 429 会返回清晰错误。
该项目处于维护模式，稳定并接收安全修复，不计划新功能，但欢迎问题和拉取请求。测试使用 mock fetch，不进行网络调用。这是一个独立的个人项目，与 Google LLC 无关联。
