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 天相比，哪 50 个查询的点击损失最大？” 助手就会提取数据，计算差值，并撰写分析。无需再导出 SQL。

Related MCP server: Google Search Console MCP

工作原理

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

两条 OAuth 链：

1. MCP 客户端 → Worker：ChatGPT/Claude 对您的 Worker 执行 OAuth 2.1 + PKCE。登录界面会要求输入您在部署时设置的静态“访问密钥”（连接器门禁）。

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.<您的子域名>.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 中的分步指南操作。在“Authorized redirect URI”中使用第 1 步中的 Worker URL。最终您将得到一个 Client ID 和一个 Client Secret。

这是耗时最长的一步（首次约 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：

• 名称：gsc

• MCP 服务器 URL：https://YOUR-WORKER-URL/mcp（必须以 /mcp 结尾）

• 身份验证：OAuth

• 勾选“I understand and want to continue”

• 创建

弹出窗口会打开您的 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 的 redirect URI 要求 HTTPS。要进行真正的端到端测试，请部署到 Cloudflare 并针对 workers.dev URL 进行测试。

限制

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

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

• OAuth 同意屏幕处于“测试”模式，最多只能有 100 个测试用户（个人/团队使用绰绰有余）。若要更广泛的发布，您需要提交应用进行 Google 验证（webmasters.readonly 是“敏感”范围，需要人工审核）。

• GSC API 配额 —— 每个项目每分钟 1200 次查询，每天 30,000 次。交互式使用完全足够。

• 日期范围 —— 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。