Google Search Console MCP by DigestSEO

mcp-gsc

属于 DigestSEO 开源 SEO 工具套件。

• 产品：digestseo.com/gsc-mcp
• 工程案例研究：DigestSEO MCP Suite — AI 可见度、Search Console、网页验证和趋势智能
• 支持：digestseo.com/support
• 隐私：digestseo.com/privacy

可自托管的启动器以 @digestseo/mcp-gsc 的形式提供：

npx -y @digestseo/mcp-gsc

npm 启动器会在 127.0.0.1 上启动一个仅限环回连接的 Streamable HTTP Worker（默认端口为 8080）；它不是 stdio MCP 进程。你可以从任意目录运行 npx 命令，因为启动器会从已安装的软件包中解析其捆绑的 Worker 配置。启动该软件包的客户端应在设置 SETUP.md 中所述的 Google OAuth 和令牌加密环境变量后，连接到 http://127.0.0.1:8080/mcp。如果缺少 GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET 或 TOKEN_ENCRYPTION_KEY，或者其值为空白，启动器会在启动 Wrangler 前退出；此外，如果非空的 TOKEN_ENCRYPTION_KEY 不是有效的 base64，或解码后不恰好为 32 字节，启动器也会拒绝它。错误信息只会指出无效或缺失的设置，不会显示其机密值，因此不会启动出错的 OAuth 会话。机密值会保留在子进程环境中，Wrangler 会通过已声明的本地机密加载这些值；它们不会被复制到 Wrangler 的 --var 命令行参数中。首次 OAuth 登录前，请在 Google Cloud 中授权确切的回调地址 http://127.0.0.1:8080/google/callback（或者使用你启动时设置的相同自定义 PORT）；启动时，启动器会打印这两个 URL。

Docker/Glama 网络绑定。 普通的 npx 启动器默认仅限环回连接（MCP_GSC_BIND_IP=127.0.0.1）。Docker 镜像会在容器内部显式设置 MCP_GSC_BIND_IP=0.0.0.0，因为 Docker 端口转发无法连接到仅绑定容器环回接口的服务。在你的计算机上发布 Docker 端口时，建议使用 -p 127.0.0.1:8080:8080 以限制主机访问；只有在部署配置了适当的 HTTPS/OAuth 且使用了获授权的 Google 重定向 URI 时，才应将其暴露到主机之外。MCP_GSC_BIND_IP 只接受 127.0.0.1 或 0.0.0.0；普通的本地 npm 使用场景中，不要绑定所有网络接口。

默认情况下，本地 KV 和 Durable Object 状态（包括加密的 Google 会话）存储在 ~/.mcp-gsc/state，而不是有版本管理的 npm 缓存中。这样可确保本地连接在升级软件包和执行常规 npm 缓存清理后仍然可用。设置 MCP_GSC_STATE_DIR 可使用其他目录；重新使用现有状态时，请保持 TOKEN_ENCRYPTION_KEY 不变，因为存储的刷新令牌使用此密钥加密。启动时，启动器会打印实际使用的状态目录。由于较早版本的启动器会将本地状态存储在 npm 软件包缓存中，首次发布此稳定路径的版本可能需要重新连接一次 Google。 本地启动器默认使用 GSC_ACCESS_MODE=readwrite。如果只需以最小权限进行分析或报告，请在运行 npx 前于环境中设置 GSC_ACCESS_MODE=readonly；启动器会将该值传递给本地 Worker，使 OAuth 请求仅申请只读 Search Console 权限范围，并且不会注册六个变更工具。

Google OAuth 和 Cloudflare 部署配置请参阅 SETUP.md。

连接本地启动器

对于当前已验证的快速连接方式，请先设置 SETUP.md 中所述的 Google OAuth 和令牌加密环境变量，然后启动 npm 启动器：

npx -y @digestseo/mcp-gsc

然后将 MCP 客户端连接到启动器的环回端点：

http://127.0.0.1:8080/mcp

可自托管的 Cloudflare Worker 部署仍使用 https://<your-worker>.workers.dev/mcp。目前，仓库未将由项目所有者托管的远程服务作为快速连接方式推荐，因为其已部署的工具契约落后于已发布的软件包。

Claude Code

claude mcp add --transport http gsc http://127.0.0.1:8080/mcp

OpenAI Codex CLI / IDE

codex mcp add gsc --url http://127.0.0.1:8080/mcp

Codex CLI 和 Codex IDE 扩展共用 MCP 配置，因此只需注册一次服务，即可让两个客户端使用相同的本地连接。使用该连接前，请先启动 npm 启动器；需要身份验证时，Codex 会打开服务的 OAuth 流程。

Cursor

将此仓库安装为 Cursor 插件后，Cursor 还会自动发现捆绑的三个 Agent Skills，它们可将 MCP 工具组合为可靠的工作流：gsc-weekly-review、gsc-indexing-triage 和 gsc-search-opportunities。上方的 添加到 Cursor 按钮仅安装 MCP 连接；捆绑的技能属于仓库的 Cursor 插件软件包。

上方的按钮和插件 MCP 配置适用于与 npm 启动器运行在同一台机器上的 Cursor。**Cursor Cloud Agents 在隔离的云端 VM 中运行，因此无法访问你电脑上的 127.0.0.1。**对于 Cloud Agents，请部署自己的、可从外部访问的 HTTPS Worker，并在 cursor.com/agents 的 MCP 控制项中添加其 /mcp URL；Cursor 在此处支持 HTTP MCP 服务和 OAuth。请勿在 Cloud Agent 中复用环回 URL。

GitHub Copilot CLI

copilot plugin marketplace add AKzar1el/mcp-gsc
copilot plugin install mcp-gsc@digestseo

通过 marketplace 安装，可使用 Copilot 的 marketplace 工作流发现和更新插件。也支持直接从仓库安装：copilot plugin install AKzar1el/mcp-gsc。Copilot 插件捆绑了相同的三个 Agent Skills 和本地环回 MCP 配置。使用插件的 MCP 服务前，请先启动 npm 启动器；插件不会替你启动或部署 mcp-gsc。

Gemini CLI

gemini extensions install https://github.com/AKzar1el/mcp-gsc

Gemini CLI 扩展捆绑了已验证的本地环回 MCP 配置，以及相同的三个 Agent Skills：gsc-weekly-review、gsc-indexing-triage 和 gsc-search-opportunities。使用扩展前，请先启动 npm 启动器；扩展不会替你启动或部署 mcp-gsc。

Kiro

使用任一安装按钮或 Copilot 插件前，请先启动 npm 启动器。首次使用时，请完成其 Google OAuth 流程。 ChatGPT — ChatGPT 无法直接连接到此环回 127.0.0.1 端点。如需私有/本地使用，请创建 OpenAI Secure MCP Tunnel，然后在与启动器相同的计算机上运行 tunnel-client，以便它能够访问 http://127.0.0.1:8080/mcp；创建 ChatGPT 应用时，选择 Tunnel 连接并选取该隧道。设置隧道需要 OpenAI tunnel_id 和运行时 API 密钥；请参阅 OpenAI 的 Secure MCP Tunnel guide。该隧道会将 MCP 服务保持为私有服务，适用于私有/开发者模式连接，不适用于公开分发插件。

或者，部署你自己的远程 Cloudflare Worker，并将其 HTTPS /mcp URL 添加为开发者模式下的自定义 MCP 应用；请参阅下文的在 AI 客户端中连接。

这是一个可自托管的 Model Context Protocol (MCP) 服务，适用于 Google Search Console。将它连接到 Claude.ai、Cursor、ChatGPT 或任何兼容 MCP 的客户端，即可直接从你自己的 Google 账号向 AI 助手询问网站的自然搜索表现——包括展示次数、点击次数、热门查询、索引状态和站点地图健康状况。

它运行于 Cloudflare Workers，并内置 Google OAuth 引导流程：在客户端中连接服务，查看 mcp-gsc 同意页面（该页面会标明发起请求的 MCP 客户端及其权限），然后使用 Google 登录并授予所请求的 Google Search Console 权限。无需复制 API 密钥，也无需管理服务账号 JSON。

工具

默认情况下（GSC_ACCESS_MODE=readwrite），此服务会公开 23 个工具。只读分析和报告工具带有 MCP 的 readOnlyHint 标记；下方的写入工具可以更改 Search Console 属性、站点地图或索引状态。将 GSC_ACCESS_MODE=readonly 设置为 readonly，即可仅请求 Search Console 只读范围，并公开 16 个不需要写入权限或单独的 Indexing API 范围的工具。

工具	访问权限	功能说明
server.capabilities	读取	列出此服务提供的所有工具，并报告本地 Google 凭据状态。connected 表示存在已存储的刷新凭据；响应还会提供 auth_status_basis 和 provider_auth_live_verified: false，因为此发现调用不会探测 Google。后续调用 Google 工具时，如果凭据已过期或被撤销，仍可能需要重新连接。无需参数。
sites.list	读取	列出已连接的 Google 账号可访问的 Search Console 资源（siteUrl、permissionLevel）。
sites.get	读取	检索一个完全匹配的 Search Console 资源，以及已连接账号对该资源的权限级别。
analytics.query	读取	查询指定日期范围内的展示次数、点击次数、点击率和平均排名，并支持维度、筛选器、安全分页和可选搜索类型。传入 dimensions: [] 可获取真正的站点总计；Google 的汇总行可能省略 keys。Search Analytics 不保证返回所有数据行，且可能只返回排名靠前的行，因此耗尽本地分页并不能证明已获取提供方的全部数据。data_state: "all" 可包含最新的初步数据，而 final 只返回已定稿数据；响应会回显 data_state 和 preliminary_data_possible，并在返回日期／小时分组时保留 Google 的不完整数据边界元数据。搜索外观的发现分两步进行：先仅按 searchAppearance 分组，以发现 Google 针对此资源返回的确切值；然后在单独的查询中筛选一个已返回的值，再按页面／查询／国家／设备／日期／小时分组。对于 search_type: "discover" 或 "googleNews"，position_supported 为 false；这些报告会显示点击次数、展示次数和点击率，但不显示平均排名，因此返回的行可能省略 position，且无法按查询分组或筛选。当前文档所述的 Search Analytics API 不会将 Search Console 专用的生成式 AI 效果报告作为专用搜索类型或筛选器选项提供，因此 generative_ai_report_isolatable 为 false。Search Console 新增的网页多模态界面筛选器同样不是文档所述的 Search Analytics API 选项，因此 multimodal_report_isolatable 为 false。
insights.page_queries / insights.query_pages	读取	从一个完全匹配的页面深入查看其 Search Console 查询，或从一个完全匹配的查询深入查看 Google 为其显示的页面，并支持 row_limit / start_row 分页。这些以查询为中心的辅助工具支持网页、图片、视频和“搜索结果”中的“新闻”标签页；由于 Discover 和 Google News 报告不提供查询数据，因此不支持它们。
urls.inspect	读取	查看 Google URL 检查报告，了解 Google 索引中目前已知的某个页面版本。这不是实时 URL 测试；移动设备易用性输出已弃用。
urls.inspect_many	读取	在一次调用中检查最多 10 个 URL 在 Google 索引中的版本，并以 3 为并发上限，同时按输入顺序返回结果。每个 URL 仍会消耗一次 Google URL 检查请求，以及服务器共享检查安全预算中的一个单位；此操作不会运行实时 URL 测试。
sitemaps.list / sitemaps.get	读取	列出已提交的站点地图，或检索一个站点地图的详细信息。lastSubmitted 表示站点地图提交至 Search Console 的时间；lastDownloaded 表示 Google 上次下载该站点地图的时间。两者都不代表站点地图文件的修改／部署时间，也不代表页面抓取／编入索引的时间戳。
insights.quick_wins / insights.cannibalization / insights.content_decay	读取	展示平均排名机会行、查询／页面重叠情况，以及按证据排序的点击量下降情况。快速获益候选项是根据 Search Console 平均排名汇总值筛选出的已观测查询／页面行，并不能证明当前排名稳定；点击率仅供参考，不作为筛选条件。流量竞争候选项的总数／占比仅针对已观测的查询／页面行，而非查询级资源真实总量；内容衰退结果仅比较两个时段均有返回的页面，不会将只在一个时段返回的行缺失视为零流量。
indexing.list_pages / analytics.compare	读取	分析获得 Search Console 展示次数的页面并比较两个时段，可选用相同的搜索类型以及查询／页面／国家／设备／搜索外观筛选器。analytics.compare 仅比较两个时段响应中均返回的维度键；某个键未出现在非穷尽的 Search Analytics 响应中时，不会将其指标视为零。默认使用已定稿的 Search Analytics 行，设置 data_state=final，并保留 Google 对省略 dataState 的处理方式；如需近期可能包含初步数据的行，请显式传入 all。由于其比较内容包含平均排名，因此不支持 Discover 和 Google News。indexing.list_pages 提供的是效果数据，而非索引覆盖情况：未出现的 URL 仍可能已编入索引；如需查看 URL 级别的索引状态，请使用 urls.inspect / urls.inspect_many。
reports.weekly_digest	读取	生成通俗易懂的七日效果报告，包含变化趋势、热门页面和一项建议操作。查询变化趋势仅比较两个每周 Search Analytics 结果集中均返回的行；Google 不保证返回所有数据行，因此某个查询未出现在有数量限制的响应中时，不会将其视为零。
sites.add / sites.delete	写入	在已连接账号的 Search Console 站点集合中添加或移除资源。由于所有权验证属于单独的 Google Site Verification/Search Console 工作流，sites.add 返回 ownership_verification_performed: false。sites.delete 会从该账号的 Search Console 站点集合中移除资源；不会删除网站本身。
sitemaps.submit / sitemaps.delete	写入	提交或移除站点地图。
indexing.status	读取	读取 Google Indexing API 对此前已提交 URL 的最新成功 URL_UPDATED / URL_DELETED 通知回执。这仅为通知元数据，不代表索引覆盖、抓取状态、索引编入完成或移除完成。由于 Google 的元数据端点使用 Indexing API OAuth 作用域，因此需要 GSC_ACCESS_MODE=readwrite。
indexing.request	写入	通过 Google Indexing API 请求编入索引。Google 目前将此 API 限制用于包含 JobPosting 结构化数据的页面，或 VideoObject 中包含 BroadcastEvent 的直播页面。不适用于提交一般网页。Google 文档所述的默认配额为每个项目每天 200 次发布请求，更新和移除共用。仍须遵守符合条件的内容类型、API 授权、配额限制和垃圾内容政策；此配额并不代表可以提交其他类型的页面或超出 Google 的限制。
indexing.remove	写入	请求为先前符合条件的 Indexing API 页面发送 URL_DELETED 通知。移除前，该 URL 必须已返回 HTTP 404/410，或显示 robots noindex 元指令。Google 的回执不能证明移除已完成；请使用 URL Inspection 查看索引状态证据。
Search Analytics 日期（start_date、end_date 和对比期日期）采用 Google 太平洋时区日历（America/Los_Angeles，根据夏令时为 UTC-8 或 UTC-7），而不是调用方的本地时区或 UTC。这也适用于服务生成的 Search Analytics 日期范围或默认日期范围。

平台属性。 Search Console 现在在其界面中支持 Instagram、TikTok、X 和 YouTube 等社交媒体／视频账号的平台属性。Google 当前的 Search Console API 文档仍将 siteUrl 定义为 URL 前缀和 sc-domain: 网站属性形式，且未公布平台属性的 API 标识符约定。因此，sites.list 会保留 Google 返回的每个标识符，并标明其是否符合文档所述的 API 语法；其他工具会有意拒绝未记录的形式，而不是自行编造标识符。Google 记录 API 支持之前，请通过 Search Console 界面或导出功能使用平台属性。

读写模式会请求 Google Search Console 读写权限范围和 Indexing API 权限范围。只读模式仅请求 https://www.googleapis.com/auth/webmasters.readonly（以及 openid 和 email），并且不会注册六个写入工具，也不会注册只读的 indexing.status 查询，因为该查询仍需要 Google 单独的 Indexing API 权限范围。默认仍为读写模式，以保留现有部署的行为；请参阅 SETUP.md，了解如何在连接用户之前选择模式。

大型分析响应会在 MCP 边界处受到限制，而不是先生成响应、再由具有结构化内容限制的客户端将其丢弃。在适用的列表类工具中，会提供 start_row / next_start_row；排名分析工具会提供 limit、start_row 和 result_page 元数据，其中包括 has_more、truncated 和 byte_limit_reached。只要 has_more 为 true，就应继续分页，不要假定单次响应已包含全部结果。

Indexing API 的适用条件与配额。 Google 的 Indexing API 并非通用的网页提交工具——截至本文撰写时，Google 官方文档将其限制为两类内容：包含 JobPosting 结构化数据的网页，以及在 VideoObject 中嵌套 BroadcastEvent 结构化数据的直播网页。执行 indexing.request 之前，服务会抓取目标 URL，并检查静态 JSON-LD、Microdata 和 RDFa 标记是否包含这两类结构化数据之一；如果两者都没有（或无法抓取网页），服务会返回错误，说明该 URL 不符合条件，而不会调用 Indexing API。仅在客户端 JavaScript 运行后注入的结构化数据无法通过此受限的预检确认，因此会按失败关闭处理。执行 indexing.remove 之前，服务会改为确认 Google 的移除前提条件：该 URL 必须已返回 HTTP 404/410，或包含 robots noindex 元指令。更新通知和移除通知共用同一发布配额。Google 当前文档列出的默认配额为每个项目每天 200 次发布请求。Google 于 2026 年 10 月 16 日的更新移除了已过时的配额申请表，但这并不意味着可以超出已公布的配额或提交不受支持的内容。请在 Google Cloud Console 中查看项目的 API 访问权限和当前配额。Google 还会对每次提交进行垃圾信息检测，并警告称，滥用或试图通过多个账号或其他方式超出配额，都可能导致访问权限被撤销。通知成功仅表示 Google 已收到该通知，并不保证索引或移除已完成。

可以询问的问题

连接后，你可以向助手询问：

• "过去 28 天，按点击次数排名前 20 的查询是什么？"
• "比较 example.com 本月和上个月的展示次数——哪些网页的表现下降了？"
• "Google 索引版本的 https://example.com/pricing 显示的索引状态和上次抓取时间是什么？"
• "哪些高展示次数的查询/网页行的平均排名在 5 到 15 之间？请列出这些优化机会。"
• "生成一份截至今天、涵盖 sc-domain:example.com 的每周摘要。"
• "我的站点地图是否存在错误或警告？"
• "使用我提供的品牌正则表达式，估算品牌相关和非品牌相关的点击次数。"
• "我的网站在 Google Discover 中的表现与常规网页搜索相比如何？"

查询正则表达式只能用于手动近似。Search Console 原生的品牌/非品牌过滤器使用 Google 自己的 AI 辅助分类（包括语言变体、拼写错误以及相关产品/服务），且该原生分类器未通过 Search Analytics API 的过滤器公开。

Search Console 还提供专门的 Search 和 Discover 生成式 AI 效果报告。目前有文档说明的 Search Analytics API 不提供专门的生成式 AI 搜索类型或过滤器选择器，因此此 MCP 不会对此进行猜测。AI Overviews 和 AI Mode 仍包含在整体网页搜索效果数据中；在 Google 记录 API 访问方式之前，请使用 Search Console 界面查看专门的生成式 AI 报告。

截至 2026 年 9 月 24 日，Search Console 界面还提供网页多模态效果过滤器，可用于 Lens、Circle to Search、图片上传和 Chrome 图片搜索等搜索。目前的 Search Analytics API 和 Discovery 文档仍只公开 web、image、video、news、discover 和 googleNews 搜索类型，因此此 MCP 不会虚构 search_type: "multimodal" 或猜测 searchAppearance 值。在 Google 记录 API 访问方式之前，请使用 Search Console 界面单独查看多模态效果报告。

在 AI 客户端中连接

部署服务器后（参见 SETUP.md），将 Worker 的 /mcp URL 粘贴到客户端即可连接：

https://<your-worker>.workers.dev/mcp

• Claude.ai / Claude Desktop — 前往 Customize → Connectors，点击 + → Add custom connector，输入名称并粘贴 /mcp URL。可选的高级 OAuth Client ID/Secret 字段留空。在 Team/Enterprise 版中，Owner 或 Primary Owner 必须先从 Organization settings → Connectors 添加自定义 Web 连接器；之后，成员可从 Customize → Connectors 进行连接。首次连接时，Claude 会打开 Google 登录流程。
• Cursor — 添加一个指向相同 /mcp URL 的远程 Streamable HTTP MCP 服务；Cursor 支持远程 HTTP MCP 服务的 OAuth。上方的 Add to Cursor 按钮会指向本地 npm 启动器的环回端点。
• ChatGPT — 启用 Developer mode，然后从 Settings → Apps → Create 创建自定义 MCP app（管理员/所有者也可以使用 Workspace settings → Apps → Create）。提供 /mcp 端点，选择适用的身份验证选项，点击 Scan Tools，完成 OAuth，然后创建 app。目前 Business 和 Enterprise/Edu 版可使用包含写入/修改工具的完整 MCP；Pro 自定义 MCP 访问权限仅限读取/提取，因此此使用路径请设置 GSC_ACCESS_MODE=readonly。

/mcp 端点在各客户端中相同，但每个宿主都有自己的设置和权限流程。

设置

自行托管意味着你需要准备自己的 Google OAuth 凭据和 Cloudflare 账户。完整的逐步指南（可直接复制粘贴）见 SETUP.md，其中还特别说明了 Google 的 OAuth 验证，以及应用未经验证时刷新令牌的 7 天有效期限制。

快速概览：

git clone https://github.com/AKzar1el/mcp-gsc.git
cd mcp-gsc
npm install
cp wrangler.example.jsonc wrangler.jsonc       # then paste in your KV ids
# set GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET / TOKEN_ENCRYPTION_KEY as secrets
# choose GSC_ACCESS_MODE=readonly in wrangler.jsonc for a read-only deployment
npm run deploy

详细步骤请参阅 SETUP.md。

开发

npm install
npm test              # typecheck + offline unit tests (what CI runs)
npm run dev           # wrangler dev (local)
npm run test:smoke    # structural smoke tests against a deployment

欢迎贡献——请参阅 CONTRIBUTING.md。

许可证

MIT © 2026 DigestSEO。

---

由 Tomi Šeregi 构建并维护，他也是 DigestSEO 背后的创建者——提供开源 SEO 工具和搜索可见度软件。