gsc-mcp-connector

自托管 Google Search Console MCP 服务器，15 分钟内可部署到 Cloudflare Workers。接入 ChatGPT、Claude 或任何支持 MCP 的客户端，用自然语言查询 GSC 数据。

它能为你提供什么

部署完成后，你将获得一个私有的 MCP 端点，为你的 AI 助手暴露 4 个工具：

• list_sites — 发现已验证用户可访问的所有媒体资源

• query_search_analytics — 点击量、展示次数、点击率、排名，可按查询/页面/国家/设备/搜索外观/日期进行筛选

• inspect_url — 完整的 URL 检查 API 输出（索引状态、规范链接、移动端、AMP）

• list_sitemaps — 所有已提交的站点地图及其处理状态

你问：“过去 28 天与前 28 天相比，哪些查询的点击量下降最多？” 助手就会拉取数据、计算差值，并撰写分析报告。无需再导出 SQL。

Related MCP server: gsc-mcp-connector

工作原理

ChatGPT/Claude  ──OAuth──▶  Your Worker  ──OAuth──▶  Google
                                 │
                                 └─ holds your Google refresh_token
                                    (encrypted, in OAuth grant props)

两条 OAuth 链路：

1. MCP 客户端 → Worker：ChatGPT/Claude 使用 OAuth 2.1 + PKCE 对你的 Worker 进行验证。登录界面要求输入你在部署时设置的静态“访问密钥”（连接器网关）。

2. Worker → Google：通过访问密钥检查后，用户被重定向到 Google 的同意屏幕，授予 webmasters.readonly 权限。生成的刷新令牌存储在 OAuth 授权中；每次工具调用时，Worker 刷新一个新的访问令牌并调用 GSC。

用户的 Google 账号驱动访问——无需服务账号、无需管理 GSC 用户、无需权限传播延迟。

前提条件

Cloudflare Workers 免费套餐（每天 10 万次请求）足以满足个人 SEO 使用。无需付费的 Cloudflare 套餐。

快速入门（约 15 分钟）

1. 部署 Worker

点击本 README 顶部的 Deploy to Cloudflare 按钮。Cloudflare 会将仓库克隆到你的账号，安装依赖，并提供一个公共 URL，如 https://gsc-mcp-connector.<your-subdomain>.workers.dev。

注意：在此阶段，系统会要求你提供 MCP_BEARER_TOKEN、GOOGLE_OAUTH_CLIENT_ID 和 GOOGLE_OAUTH_CLIENT_SECRET。此时你还没有 Google 相关的信息——请先为 MCP_BEARER_TOKEN 填写任意随机十六进制字符串（后续可更改），并在两个 Google 字段中粘贴任意内容。我们将在步骤 4 中进行正确设置。

如果你希望跳过按钮，也可以本地克隆仓库，运行 npm install，然后执行 npx wrangler deploy。

部署完成后，请记下你的 Worker URL。你在步骤 3 和步骤 5 中都会用到。

2. 生成连接器访问密钥

这是一个静态随机字符串，用作 Google OAuth 之前的门控。任何使用连接器的人都必须在登录界面中粘贴此字符串。

openssl rand -hex 32

保存输出——你将把它设置为密钥，并在 ChatGPT/Claude 中使用。

3. 设置 Google Cloud（OAuth 客户端）

请按照 docs/SETUP_GCP.md 中的逐步说明操作。在“已授权的重定向 URI”中，使用步骤 1 中的 Worker URL。完成后，你将获得一个 客户端 ID 和一个 客户端密钥。

这是耗时最长的步骤（首次约 10 分钟），但只需执行一次。

4. 配置 Worker 密钥

npx wrangler secret put MCP_BEARER_TOKEN
# paste the value from step 2

npx wrangler secret put GOOGLE_OAUTH_CLIENT_ID
# paste the Client ID from step 3

npx wrangler secret put GOOGLE_OAUTH_CLIENT_SECRET
# paste the Client Secret from step 3

或者通过 Cloudflare 仪表盘：Workers & Pages → 你的 Worker → Settings → Variables and Secrets → 将每项添加为 Secret 类型。

提示——Windows 编码陷阱：如果你通过管道传递文件内容（例如 Get-Content | wrangler secret put），且该文件含有 UTF-8 BOM，则 BOM 会被包含在密钥中，导致 JSON 解析失败。使用 Cloudflare 仪表盘或交互式 wrangler secret put（在提示符下粘贴）可完全避免此问题。

5. 接入 ChatGPT（Plus/Pro/Team）

ChatGPT → Settings → Connectors → Add custom connector：

• Name : gsc

• MCP Server URL : https://YOUR-WORKER-URL/mcp（必须以 /mcp 结尾）

• Authentication : OAuth

• 勾选“我理解并希望继续”

• Create

将弹出一个窗口，打开你的 Worker 登录界面。粘贴你的 MCP_BEARER_TOKEN → 点击 Continue with Google → → Google 要求你登录（使用拥有 GSC 媒体资源的账号）并授予 webmasters.readonly 权限 → 你将被重定向回 ChatGPT，连接器已激活。

在新的聊天中，在工具栏中启用 gsc 连接器，然后提问：“列出我的 Google Search Console 网站。” 你应该能看到你的媒体资源。

6.（可选）接入 Claude.ai（Pro/Team）

Settings → Integrations → Add custom integration → 相同的 URL，相同的流程。

本地开发

git clone https://github.com/JuJu78/gsc-mcp-connector
cd gsc-mcp-connector
npm install
cp .dev.vars.example .dev.vars
# edit .dev.vars with your real Client ID + Client Secret + bearer token
npx wrangler dev

开发服务器运行在 http://localhost:8787。请注意，本地开发无法完全完成 Google OAuth 流程，因为 Google 的重定向 URI 要求使用 HTTPS。如需完整的端到端测试，请部署到 Cloudflare 并使用 workers.dev URL 进行测试。

限制

• 只读。 有意未包含写入操作（提交站点地图、请求索引）——它们在 LLM 上下文中具有风险。如有需要，请提交 PR。

• 单租户设计。 一个操作者部署，一个 Bearer 令牌门控连接器，访问权限绑定给完成 Google OAuth 流程的人。多用户 SaaS 风格不在范围内。

• OAuth 同意处于“测试”模式，限制最多 100 个测试用户（个人/团队使用绰绰有余）。如需更广泛分发，你需要提交应用进行 Google 验证（webmasters.readonly 属于“敏感”范围，需要人工审核）。

• GSC API 配额 — 每分钟 1200 次查询/项目，每天 3 万次。对交互式使用绰绰有余。

• 日期范围 — GSC 返回最近 16 个月的数据。更早的日期会出错。

故障排除

技术栈

• Cloudflare Workers + Durable Objects（通过 agents SDK ≥0.12）

• @cloudflare/workers-oauth-provider 用于 OAuth 2.1 + DCR + PKCE

• @modelcontextprotocol/sdk 用于工具定义

• KV 命名空间 OAUTH_KV 用于 OAuth 状态

• Google OAuth 2.0 流程原生使用 Web Crypto API 签名（无 Node 依赖）

鸣谢

由 Julien Gourdon 构建——一位探索搜索与 AI 交叉领域的 SEO 顾问。

许可证

MIT — 参见 LICENSE。