Skip to main content
Glama

GSC Agent

English · 简体中文

让你本机的 AI agent(Claude Code、Codex、Cursor、Claude Desktop 等)借用你在 Chrome 中已登录的 Google Search Console,替你为网址点击「请求编入索引」,并如实报告 Google 是否确认。

  • 不需要 Google OAuth、API Key 或 Google Cloud 项目,用的就是你浏览器里的登录状态。

  • agent 只能操作你点击扩展图标绑定的那一个 GSC 标签页。

  • 读到 Google 的确认才报告「已提交」,不确定时如实说明。

能做什么

  • 单个或批量提交:给 agent 一个或一组网址,它在后台按顺序处理,同批重复的网址只处理一次。

  • 三种模式:submit 直接请求编入索引(适合更新过的页面);inspect 只检查是否已收录;if_unindexed 先检查,明确未收录才提交。

  • 自动选资源:按网址自动切换到对应的 GSC 资源,网址前缀资源和网域资源都支持,选匹配最具体的那个。

  • 保护配额:按资源统计 24 小时内的提交次数,到上限自动停下。批次中每次提交后默认间隔 120 秒,降低被限流的风险。

  • 可停止、可续跑、可追溯:批次可以随时停止,未开始的网址可以交给新批次接着跑;每次操作都记录在本机。

  • 自检:一条命令检查安装、浏览器连接和版本是否一致,并给出修复办法。

不能做的事:不能保证 Google 收录(只负责把请求送到);不读取搜索表现数据,也不提交 sitemap。

Related MCP server: search-console-mcp

工作原理

AI agent ──MCP──> 本机 MCP 服务 ──套接字──> 本机宿主 ──原生消息──> Chrome 扩展 ──> 你的 GSC 标签页

扩展在页面中执行的操作和你手动操作一样:填写网址检查框、等待报告、点击「请求编入索引」、读取确认框。

环境要求

  • macOS 与 Google Chrome

  • Node.js 22.22 或更高版本

  • GSC 界面语言为简体中文或英文(其他语言见维护自己的版本)

安装

git clone https://github.com/Patrick5D/gsc-agent-extension.git gsc-agent
cd gsc-agent
npm install
npm run setup

setup 把扩展和本机宿主复制到 ~/.gsc-agent/,在 Chrome 中注册宿主,然后打印后续步骤:

  1. 打开 chrome://extensions,开启「开发者模式」,点击「加载已解压的扩展程序」,选择 ~/.gsc-agent/extension(setup 会打印完整路径;在选择框中按 ⌘⇧. 可显示隐藏目录)。

  2. 把 MCP 服务加入你的 agent,见下一节。

  3. 在 Chrome 打开已登录的 GSC 资源页,点击扩展图标,徽标显示 ON 即已连接。

  4. 运行 npm run doctor,全部打勾即可使用。

接入 agent

运行 npm run config 打印所有客户端的配置,或者指定一个客户端:npm run config -- claude-code。可选的客户端有 claude-code、codex、cursor、claude-desktop、json。配置里使用 Node 和本仓库的绝对路径,图形界面客户端也能找到。

单条提交最长需要约 4 分钟,请把客户端的工具超时调到 270 秒以上:

  • Claude Code:用 MCP_TOOL_TIMEOUT=270000 claude 启动。

  • Codex:在 ~/.codex/config.toml 的 [mcp_servers.gsc-agent] 段加入 tool_timeout_sec = 270。

  • 不能调超时的客户端:让 agent 用 gsc_start_batch 处理单个网址。它立即返回,之后用 gsc_batch_status 查结果。

接好后重启客户端,确认工具列表中有 gsc_request_indexing。

使用

直接用自然语言告诉 agent,例如:

  • 「用 gsc_request_indexing 提交 https://example.com/article」

  • 「检查这 20 个网址有没有收录,只提交没收录的,做完逐条告诉我结果。」

  • 「查一下这个网址最近一次有没有确认提交,给我报告链接。」

重启 Chrome 后,要在 GSC 页面重新点一次扩展图标。想换一个标签页,在新标签页上点图标即可重新绑定。

工具

工具

作用

gsc_request_indexing

处理单个网址,参数:url、mode、skip_recent_hours

gsc_start_batch

后台按顺序处理一组网址,立即返回批次 id。参数:urls、mode、interval_seconds、skip_recent_hours

gsc_batch_status

查看批次进度、每条结果、进行中的网址和未开始的网址

gsc_stop_batch

停止批次,进行中的网址会先执行完

gsc_submission_history

查询本机操作记录,可按 url、status 筛选

gsc_doctor

检查安装、连接和版本,返回修复建议

skip_recent_hours:如果该网址在指定小时内已有确认过的提交,就跳过。默认 0,即不跳过。

结果状态

  • submitted:GSC 已确认收到请求。是否收录由 Google 另行决定。

  • inspected / already_indexed:检查完成,或已收录而跳过。

  • recently_submitted:命中 skip_recent_hours,按本机记录跳过。

  • blocked:点击提交前停下,比如未登录、找不到资源、遇到配额或出错提示。

  • unconfirmed:已经点了提交,但没读到明确确认。请先查看标签页,再决定要不要重试。

批次、间隔与配额

  • 同一时间只运行一个批次。批次运行期间,单条工具和新批次都会被拒绝。

  • 每次确认提交后等待 interval_seconds 秒(默认 120),只读检查之间最多等 3 秒。等待期间 nextAt 给出下一条的开始时间。

  • 遇到错误,或成功框需要手动关闭时,批次会停下。把 remaining 交给新批次即可续跑。

  • GSC 每个资源每天大约只能提交 10 次。本机按资源统计 24 小时内已点击的提交(未确认的也计入)。达到 GSC_AGENT_DAILY_QUOTA(默认 10)后,submit 模式在检查前停下,if_unindexed 模式在检查后、点击前停下。在 MCP 配置里设置这个环境变量可以调整上限,设为 0 关闭。手动在 GSC 页面提交的次数不会计入。

  • Chrome 会放慢后台标签页的定时器。跑长批次时,建议把绑定的标签页单独放在一个可见窗口里。

操作历史

记录保存在 ~/.gsc-agent/history/,批次快照保存在 ~/.gsc-agent/batches/。每次操作开始时写入 started,结束后补上资源、结果或错误。如果进程中断,started 表示结果待核实。

自检与排错

运行 npm run doctor,或让 agent 调用 gsc_doctor,按提示处理。常见情况:

现象

处理

徽标显示 OFF,提示找不到 native messaging host

运行 npm run setup,然后在 chrome://extensions 刷新扩展

「请在已登录的 GSC 标签页点击扩展图标」

在 GSC 资源页点击扩展图标,徽标显示 ON

「找不到网址检查框」或一直等不到报告

把 GSC 界面语言切换为简体中文或英文,或按 CUSTOMIZE.md 添加规则

工具调用超时

调大客户端超时,或改用 gsc_start_batch

切换或删除过 Node 版本

重新运行 npm run setup

批次在后台很慢

把绑定的标签页放到单独的可见窗口

升级与卸载

  • 升级:git pull && npm install && npm run setup,然后在 chrome://extensions 刷新扩展,在 GSC 页面重新点击图标,再重启 agent 的 MCP 连接。

  • 卸载:node bridge/cli.js uninstall,然后在 chrome://extensions 移除扩展。操作历史会保留在 ~/.gsc-agent/。

维护自己的版本

所有可定制项集中在两个文件里:GSC 页面文案规则、宿主名和等待时间在 extension/config.js,数据目录和默认值在 bridge/config.js。增加界面语言、适配 GSC 改版、换成自己的扩展 ID 等做法,见 CUSTOMIZE.md。

局限与风险

  • 本工具操作的是 GSC 网页,不是官方 API。GSC 改版可能导致它失效,失效时按 CUSTOMIZE.md 更新规则即可。

  • 自动操作网页的用法是否符合 Google 的服务条款,请自行判断。请把提交频率控制在正常人工使用的范围内。

  • 目前只支持 macOS 上的 Google Chrome。

开发与测试

npm test

测试包括:用模拟的 Chrome 消息验证 MCP 到本机宿主的完整链路;用 jsdom 模拟页面验证页面脚本;验证命令行的安装、自检与卸载。测试不会向 Google 提交任何请求。模拟页面是按本项目对 GSC 页面结构的假设搭建的,不能代替在真实页面上核对。

许可证

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Provides AI agents with read-only access to Google Search Console data, including search analytics, index coverage, and sitemap status. It enables users to query clicks, impressions, and ranking performance or check URL indexing status through natural language.
      4
      133 npm
      9
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to access Google Search Console search performance and index health data, including clicks, impressions, rankings, URL inspection, and sitemap management.
      22 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to query and analyze Google Search Console data, including search analytics, URL inspection, sitemaps, and property verification, and to perform actions like submitting sitemaps and adding properties through natural language.
      19
      24 npm
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants to access search analytics from Google Search Console and Bing Webmaster Tools, inspect URL indexing, monitor sitemaps, and submit URLs to search engines via IndexNow.
      7
      MIT