gsc-indexer-mcp

Google Search Console MCP Server

一个 MCP 服务，让 Claude 和其他 AI Agent 能够真正操控 Google Search Console——列出你的资源、检查 URL 是否已编入索引、找出 Google 遗漏的页面、批量运行 URL 检查、提交站点地图、请求编入索引，并通过对话获取搜索分析数据。

专为厌倦了逐个资源手动检查索引状态和提交站点地图的 SEO 从业者，以及能代劳的 AI Agent 打造。

shahidali.co/tools/gsc-mcp 是项目页面：包含相同的安装 命令、工具列表，以及实际的配额规则，供尚未浏览过此代码仓库的用户参考。

目录

• 添加到你的 Agent — Claude Code、Cursor、VS Code、LM Studio 的一键命令
• 项目状态 — 已验证的内容，以及经过验证的平台数量
• 工具 — 此服务注册的 15 个工具
• 为什么配额核算是难点
• 查找未编入索引的内容 · 原因代码
• 提交 URL · 使用哪个工具 · 首次提交前须知
• 要求
• 安装 · OAuth 客户端由你代劳 · 改用自己的 OAuth 客户端
• 开始使用 — 首次运行、登录、浏览器扩展
• 开发 · 架构
• 隐私 — 哪些数据会离开你的设备，哪些不会
• 已知不足 — 将其用于客户资源前请先阅读
• 贡献 · 许可证

添加到你的 Agent

Claude Code，一条命令即可：

claude mcp add gsc -- uvx gsc-indexer-mcp

其他所有支持 MCP 的客户端，手动配置——完整配置如下：

{
  "mcpServers": {
    "gsc": { "command": "uvx", "args": ["gsc-indexer-mcp"] }
  }
}

uvx 会获取并运行已发布的软件包，无需预先安装任何内容， 因此上面的按钮都只需一条命令。此代码仓库中包含一个内容完全相同的 .mcp.json，所以克隆代码仓库也足够了。

这些配置都不需要 API 密钥。首次调用 gsc_setup() 时，只需在浏览器中 登录一次——请参阅OAuth 客户端由你代劳。

---

项目状态

Beta。整个功能面均已接通，并且现已在一种操作系统上，由一位用户使用真实 Google 账号完成验证。

0.1.0 移除了预发布后缀，因此运行 pip install 时无需添加 --pre。这是为了扩大覆盖范围，并非宣称项目已成熟：本项目需要来自作者之外的用户提交错误报告，而默认拒绝安装的软件包不会收到这些报告。在将其用于你在意的资源之前，请先阅读 CHANGELOG.md 中的已知问题——特别是，Google 暂时性的速率限制目前会导致整个批次终止。发现问题正是我们所期待的；请提交错误报告。

服务上注册了 15 个工具，并通过线级冒烟测试覆盖；该测试会连接真实 MCP 客户端会话，并确认每个工具都能返回描述。存储、配额核算、OAuth 和配置是这些工具的基础。我们已在 Windows 上使用真实 Google 账号实际走通登录流程——请参阅 docs/manual-smoke.md，其中也记录了测试发现的缺陷。此后，提交功能已驱动真实浏览器，并获得 Google 确认的真实 Request Indexing 调用；测试使用 Chrome 和 Brave，针对真实资源进行。验证仅覆盖一个平台和一位操作者，而且所有关于此功能的自动化断言仍使用模拟对象；请参阅“已知差距”，了解这能说明什么、不能说明什么。

里程碑	范围	状态
1. 基础	路径、日志记录、SQLite 存储、配额引擎、OAuth + PKCE、配置	已完成
2. MCP 功能面	下方列出的工具，通过 MCP 提供	已完成
3A. 入门设置	引导式登录、浏览器／配置文件检测、桥接扩展	已完成
3B. 提交	由浏览器驱动的 Request Indexing、作业控制	已在 Windows 上验证实际运行
4. 报告	索引发现与审核	已在 Windows 上验证实际运行

已发布的版本及其变更内容见 CHANGELOG.md。如果你想了解上述里程碑何时在 Windows 以外的平台通过验证，请关注或为仓库点星。

工具

目前已发布并注册到 MCP 服务的工具：

工具	功能
gsc_list_sites	列出账号可访问的所有 Search Console 资源
gsc_doctor	诊断身份验证、配置和环境问题
gsc_check_status	通过 URL Inspection API 检查一个或多个 URL 的索引状态（只读，不消耗 Request-Indexing 配额）
gsc_quota	按资源显示今天剩余的 Request-Indexing 和 URL Inspection 配额
gsc_performance	获取 Search Analytics 中的点击次数、展示次数、CTR 和排名
gsc_submit_sitemaps	向某个资源提交或重新提交站点地图
gsc_setup	引导完成登录和设置；具备幂等性，每次仅返回下一个步骤
gsc_detect_browsers	查找已安装的浏览器和配置文件，以便通过浏览器驱动提交
gsc_use_browser	指定要驱动的浏览器配置文件，覆盖检测器的推荐结果
gsc_request_indexing	逐个提交最多 5 个 URL 以供索引。会阻塞数分钟——请参阅提交 URL
gsc_start_indexing_job	将任意数量 URL 的后台提交任务加入队列；立即返回
gsc_job_status	查看一个提交任务或最近一个任务的进度和状态
gsc_stop_job	请求正在运行的提交任务在处理完当前 URL 后停止
gsc_find_unindexed	查找某个资源中哪些 URL 尚未编入索引，以及原因——请参阅查找尚未编入索引的内容
gsc_audit	从本地存储读取某个资源当前的索引状态；不消耗配额

为什么配额核算最棘手

这个领域的大多数工具都会弄错 Google 的限制，接着被限流，然后怪罪检测机制。两个关键限制都按资源（property）计算，而非按账号计算：

限制	数值	机制
请求编入索引	每个资源约 11 个名额	滚动计算——每个名额在使用后 24 小时 + 1 分钟释放
URL 检查	每个资源每天 2,000 次	每日重置
URL 检查	每个资源每分钟 600 次	速率限制

各个资源互相独立，因此八个资源就有八份独立配额。此服务会逐个跟踪名额，而不是统计每日总量，因此能准确知道下一个名额何时开放；如果可能发生竞争，它会刻意多计而不漏计，因为短暂等待比遭遇硬性的 Quota Exceeded 更划算。

查找未编入索引的内容

gsc_find_unindexed 会收集候选 URL——来源可以是资源已登记的站点地图、本地存储中已有的 URL，或两者兼有——检查上次检查已过期的 URL，并报告每个未编入索引的 URL 及其原因。limit 限制的是接受检查的 URL 数量，而不是返回结果的数量：检查会消耗配额，如果上限只裁剪输出，就会为一个随后被丢弃的答案付出全部代价。达到上限的运行会按存储自身的 URL 排序（字母顺序）处理 URL，而不是优先处理过期最久的 URL，因此这只是抽样，而非优先处理最差情况的全面检查。

gsc_audit 仅根据存储回答同一个问题——不进行 HTTP 检查，也不消耗配额。它反映的是某个时间点的情况：报告上次检查的结果，并提供 as_at 和 stale 计数，让你了解这份快照有多旧。它有意不提供任何变化数据。

原因代码

共有十种。每行的 submitting_helps 表示调用 gsc_request_indexing 前应采取的行动：

原因	submitting_helps	含义
discovered-not-indexed	yes	Google 知道这个 URL，但尚未抓取
unknown-to-google	yes	Google 从未见过这个 URL
crawled-not-indexed	yes	Google 抓取过，但选择不将其编入索引——先改进内容，然后提交
404	no	URL 返回未找到
redirect	no	URL 重定向到了其他位置
noindex	no	页面或其响应中包含 noindex 指令
soft-404	no	返回 200，但内容看起来像错误页或空页面
robots-blocked	no	robots.txt 屏蔽了该 URL
duplicate	no	Google 选择了另一个规范页面
alt-canonical	no	这是一个指向自身规范页面的备用页面——无需操作

如果你读过设计说明中的八种代码，却在这里数出了十种，多出来的两种是 discovered-not-indexed 和 unknown-to-google。它们是有意与 crawled-not-indexed 区分开的。这三种情况对于“一个配额名额能否改变现状”的回答都是可以，但对于“我应该先做什么”却并非如此，而后者才是你要采取行动的依据。对于已发现和未知的页面，Google 尚未作出判断——它还没有抓取这些页面，因此提交就是全部补救措施。对于未编入索引的已抓取页面，Google 已经抓取并选择不予收录；重新抓取或许能推翻这一判断，但重新提交完全相同的内容，只会得到相同的重新抓取结果。先改进页面，再提交。

每个资源每天滚动可用的名额大约只有 11 个，而且用后无法恢复。在实际网站上，crawled-not-indexed 通常是数量最多的一类。submitting_helps: true 表示这个名额有可能起作用，并不意味着今天就该用掉它。

如果无法确定某个 URL 的状态——例如检查失败，或复查无法确认结果——就会将其报告为 undetermined，绝不会报告为未编入索引。没有证据不等于已有结论。

提交 URL

Google 没有可供此类工具使用的 Request Indexing API，因此提交操作会通过你自己的浏览器进行：加载到你在 gsc_setup 期间配对的配置文件中的桥接扩展，会在真实的 Search Console 会话中点击 Request Indexing。在开始操作前，有三点值得了解。

速度很慢，而慢正是它的特点。 提交间隔为 130–180 秒。这个间隔不是占位符，也不是错误报告——这是经过验证、长时间运行时不会触发限流的间隔。因此，提交五个 URL 最多需要十五分钟的实际时间，而执行该操作的工具在这段时间内会一直阻塞。

每个资源的配额都很少。 每个资源大约有十一个名额，按滚动的 24 小时窗口计算——每个名额会在使用后 24 小时零一分钟释放，而不是在午夜释放。各资源的配额彼此独立。请先调用 gsc_quota，并根据 spendable_free 而不是 free 采取行动：spendable_free 会扣除你在配置中预留的 daily_reserve。名额一旦用掉便无法恢复；没有撤销操作。

一次只能运行一项任务。 桥接扩展会驱动真实配置文件中的单个浏览器标签页，并监听一个固定的本地端口，因此已有任务运行时，第二项任务会被直接拒绝，而不会进入队列。这适用于两个方向：当任务或 gsc_request_indexing 调用正在进行时调用 gsc_start_indexing_job，以及当任务正在运行时调用 gsc_request_indexing。

使用哪个工具

你的情况	使用	原因
有一到五个 URL，并且可以等待	gsc_request_indexing	同步执行。返回每个 URL 的结果。最多只能提交五个——配置中的 sync_submit_cap 可以调低此上限，但不能调高。
超过五个 URL，或想继续使用当前会话	gsc_start_indexing_job	立即返回 job_id；任务会在后台继续运行。没有数量上限。
有任务正在运行	gsc_job_status	查看进度、每个 URL 的结果，以及工作进程是否仍在处理任务。不带参数调用时，会报告最近的任务。
想结束某项任务	gsc_stop_job	会在当前 URL 处理完后停止，不会在 URL 处理过程中停止：已发出的提交已经消耗了名额，其账本记录必须根据实际结果结算。

出错时运行会如何处理

如果服务器已经开始拒绝请求，任务会提前停止，而不是继续消耗批次中的剩余名额：遇到 quota_exceeded、验证码、速率限制或已登出会话时，任务都会结束。结果中的 stopped_early 和 stop_reason 会说明这一点，尚未尝试的 URL 会保留其名额。以这种方式结束的任务会进入 stopped_throttled 状态；你手动停止的任务则会进入 stopped_user 状态。

无法路由到任何已知资源的 URL 会返回 no_property，而没有可用名额的 URL 会返回 no_quota。这两种情况都不会到达浏览器，也不会产生费用——它们会与失败情况分开报告，因为处理方式不同：对于第一种情况，请运行 gsc_list_sites；对于第二种情况，请等待。

如果任务运行期间服务器重启，该任务的记录会在下次启动时关闭并标记为 failed，任何仍未关闭的提交记录都会根据对应资源的账本结算。任务不会在后台静默恢复——后台工作进程无法在拥有它的进程退出后继续运行。

首次提交前

扩展必须加载到你配对的浏览器配置文件中，并且该浏览器必须是此服务器可以驱动的浏览器。gsc_setup 会引导你完成这两项操作；gsc_doctor 会重新检查它们。如果浏览器已关闭，auto_launch_browser（默认开启）会将其打开。首次运行时会将所有扩展与桥接程序配对，因此需要将浏览器窗口置于前台。

要求

• Python 3.11 或更高版本
• 拥有 Search Console 资源的 Google 账号
• Chromium 浏览器——Chrome、Brave、Edge、Vivaldi、Opera 或 Chromium。gsc_setup 会将浏览器扩展加载到你现有的某个配置文件中，没有 Chromium 浏览器就 无法完成设置。Firefox 和 Safari 都不是 Chromium 浏览器，因此无法使用。
• 无需配置 Google Cloud。gsc_setup 会获取本项目附带的 OAuth 客户端。你也可以 提供自己的客户端——请参阅下文的安装说明。

安装

此发行包名为 gsc-indexer-mcp。请注意其中的 indexer：PyPI 上单纯叫 gsc-mcp 的项目由另一位作者维护，与本项目无关，因此安装该名称会得到他人的服务。本项目中 的名称仍然都是 gsc_mcp——导入包、控制台脚本和配置目录均如此。

pip install gsc-indexer-mcp

版本 0.1.0a6 及更早版本都是预发布版本，需要使用 --pre。 从 0.1.0 开始则不需要。

也可以完全跳过安装，让 uvx gsc-indexer-mcp 按需获取；本页顶部的按钮就是这样做的。

你也可以下载 最新发布版本 中的 wheel——它有一处区别，详见下文：它附带 OAuth 客户端，而 PyPI 构建版本会在首次设置时下载该客户端。

也可以从代码检出版本安装，如果你打算修改任何内容，建议采用这种方式：

git clone https://github.com/Mrshahidali420/google-search-console-mcp.git
cd google-search-console-mcp
python -m venv .venv
.venv/Scripts/python -m pip install -e .   # POSIX: .venv/bin/python

OAuth 客户端已为你处理好

你无需创建 Google Cloud 项目。gsc_setup() 会按以下顺序查找客户端——环境变量、发布版 wheel 中内置的客户端，然后一次性下载本项目提供的客户端，并将其缓存到配置目录中。源代码检出版本会采用第三种方式；首次运行之后，所有操作都可离线完成。

跟踪的源代码中有意不包含客户端。提交到公开代码库中的密钥会永久留在 git 历史记录中；GitHub 还会向 Google 报告 Google 客户端密钥，Google 可能会撤销这些密钥，从而导致所有用户同时无法使用。因此，客户端改为通过发布资源和构建时注入的方式提供；具体机制见 docs/google-cloud-oauth.md。需要说明的是：该资源是公开的，任何人都能读取，就像 wheel 一样。它的作用是支持轮换，而非保密——已安装应用的安全性来自 PKCE，本项目正是采用了 PKCE。

改用自己的 OAuth 客户端

可选。如果你希望授权同意页面显示自己的应用名称，或组织要求使用自己的客户端，建议这样做。设置 GSC_MCP_CLIENT_ID 和 GSC_MCP_CLIENT_SECRET，即可覆盖上述所有配置，无论是发布版本还是源码检出版本都适用。

所有操作都在 Google Cloud Console 中完成，免费，约需 5 分钟。请按顺序操作——第 4 步最容易被跳过，跳过后会在最后一步失败。

1. 创建项目。 使用顶部栏中的项目下拉菜单 → 新建项目。名称不限。等待项目创建完成，然后确认该项目已在下拉菜单中选中；以下所有操作只适用于当前选中的项目。

2. 启用 Search Console API。 在控制台搜索栏中搜索“Search Console API”，打开后点击 启用。如果未启用，所有调用都会返回提及 API 已停用的 403 错误。

3. 配置 OAuth 同意屏幕。 在左侧菜单中选择：API 和 服务 → OAuth 同意屏幕。

   • 用户类型：外部。（只有 Workspace 账号才有“内部”选项，而且会限制应用仅供你所在的组织使用。）
   • 应用名称：任意名称——只有你自己会看到。
   • 用户支持电子邮件和开发者联系电子邮件：填写你自己的地址。
   • 你无需在此处添加范围。此服务会在登录时请求相应范围，在此屏幕添加范围不会改变你获得的授权。
   • 一直保存到流程结束。

4. 发布应用——或将自己添加为测试用户。两种方式都可行；建议发布，这是最容易被跳过的一步。

   所有新应用最初都处于测试状态，此时 Google 只允许列出的测试用户登录。其他人会在同意屏幕上收到 403: access_denied 错误——即使此前已经创建项目、启用 API、创建客户端、设置环境变量并运行了 gsc_setup。之前的任何步骤都不会发出提示。处于测试状态的应用还会每 7 天使刷新令牌过期，因此一周后登录会失败，表面上像是此处的程序出了问题，实际上并非如此。

   Google 将两个 Search Console 范围都归类为非敏感，因此发布无需花费：不需要验证或安全评估，也没有用户数量上限。选择 受众 → 发布状态 → 发布应用，上述两个问题就都能解决。

   如果你更愿意保持测试状态，请找到测试用户（新版控制台中：受众 → 测试用户），并添加拥有你 Search Console 资源的 Google 地址。这样你自己的账号可以一直使用，但需要每 7 天重新登录一次。

5. 创建 OAuth 客户端。 选择 API 和服务 → 凭据 → 创建凭据 → OAuth 客户端 ID，应用类型选择桌面应用。 复制显示的客户端 ID 和客户端密钥——密钥只显示一次，不过你随时可以再创建一个客户端。

   桌面应用是正确的类型：此服务会通过 127.0.0.1 上的环回重定向让你登录，这正是该类型允许的方式。不要选择“Web 应用”，也不要手动添加重定向 URI。

6. 在启动服务前设置以下两个环境变量。 如果未设置，所有需要与 Google 通信的工具都会返回 {"ok": false, "error": "not_configured", ...}，而不会执行任何操作——gsc_list_sites、gsc_check_status、gsc_performance 和 gsc_submit_sitemaps 都是如此。gsc_doctor 和 gsc_quota 是两个例外：gsc_doctor 仍会运行，并在检查列表中用一行报告 oauth_client: not ok，而不是直接失败；因此遇到问题时，它是最适合首先运行的工具。gsc_quota 仅在本地运行，无论 OAuth 配置如何，在存储为空时都会返回 []。

export GSC_MCP_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GSC_MCP_CLIENT_SECRET="your-client-secret"
# Windows PowerShell:
#   $env:GSC_MCP_CLIENT_ID = "your-client-id.apps.googleusercontent.com"
#   $env:GSC_MCP_CLIENT_SECRET = "your-client-secret"

将其连接到 MCP 客户端

将 MCP 客户端指向已安装的控制台脚本。对于 Claude Desktop，请将以下内容添加到其 claude_desktop_config.json：

{
  "mcpServers": {
    "gsc-mcp": {
      "command": "C:\\path\\to\\google-search-console-mcp\\.venv\\Scripts\\gsc-mcp.exe",
      "env": {
        "GSC_MCP_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GSC_MCP_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

在 POSIX 系统上，请改用 .venv/bin/gsc-mcp 作为命令。任何其他能够启动 stdio 服务的 MCP 客户端也采用相同方式——入口点是上文安装的 gsc-mcp 控制台脚本，服务通过标准 MCP stdio 传输进行通信（gsc_mcp.server:main）。

已在 Windows 上通过真实 MCP 客户端会话，使用真实 Google 账号进行了测试；但尚未专门在 Claude Desktop 上测试，也未在 macOS 或 Linux 上运行。请参阅已知不足。

开始使用

安装并连接服务后，整个设置过程只需反复调用一个工具。gsc_setup() 具有幂等性：它绝不会恢复会话，每次调用都会重新读取完整状态，并返回下一步要做的唯一事项。循环调用，直到它返回 ok: true。

1. 安装并连接——请参阅上文的安装。

2. 无需操作。 OAuth 客户端会为你处理——gsc_setup() 会在首次运行时下载并缓存它。只有在你想要使用自己的 OAuth 客户端时，才需要设置 GSC_MCP_CLIENT_ID 和 GSC_MCP_CLIENT_SECRET。

3. 运行 gsc_setup()。 它会在浏览器中打开 Google 授权页面，并返回页面 URL，因此无头机器也可以手动完成授权。批准授权后，再次调用 gsc_setup()——第二次调用会接收重定向、存储令牌并继续下一步。不会向调用方返回任何与你登录相关的信息：既不会返回令牌，也不会返回授权码或 PKCE 验证器。

4. 加载桥接扩展。 gsc_setup() 会告诉你扩展解压到的位置，以及要将其加载到哪个浏览器配置文件中。在该浏览器中：打开扩展程序页面（chrome://extensions、brave://extensions、edge://extensions 等——gsc_setup() 会提供适用于你浏览器的确切 URL），开启开发者模式，选择加载已解压的扩展程序，然后选择它指定的文件夹。

你会看到警告横幅，这是预期的。 该扩展会请求 debugger 权限，因此 Chromium 会显示醒目的横幅，提示有扩展正在调试你的浏览器；启用开发者模式时也可能会出现警告。此权限并非无关紧要。Search Console 会对并非由真实指针触发的“请求编入索引”点击进行软限流，而合成的 DOM 点击会触发限流。因此，该扩展会改为通过 Chrome DevTools Protocol 发送受信任的输入事件；debugger 授予的正是此权限，而且这是唯一能授予该权限的方式。横幅只是 Chromium 在正确报告一项真实功能——应将其理解为“是的，这就是你刚安装的扩展程序”，而不是恶意软件。它只会连接到 search.google.com，这是其 host_permissions 中唯一的主机。

5. 运行 gsc_doctor()。 按顺序执行七项检查：oauth_client、token、config、store、properties、browser、extension。每项失败的检查都会附带具体的 fix。以下是在一切运行正常的机器上的示例输出：

{
  "ok": true,
  "checks": [
    {"name": "oauth_client", "ok": true, "detail": "configured", "fix": ""},
    {"name": "token", "ok": true, "detail": "token file present", "fix": ""},
    {"name": "config", "ok": true, "detail": "config valid", "fix": ""},
    {"name": "store", "ok": true, "detail": "schema version 2", "fix": ""},
    {"name": "properties", "ok": true, "detail": "2 properties", "fix": ""},
    {"name": "browser", "ok": true,
     "detail": "Google Chrome / Default is the profile to use", "fix": ""},
    {"name": "extension", "ok": true,
     "detail": "the gsc-mcp bridge extension is installed in Google Chrome / Default at version 1.10.0; whether its background service worker is running is not checked in this milestone",
     "fix": ""}
  ]
}

查看浏览器和扩展程序检查结果

这两项与本地计算机有关，而非 Google 账号；相关措辞经过了谨慎斟酌，因为很容易误读失败情况。

“无法检查”绝不意味着“未安装”。 扩展程序检查会读取浏览器自身的偏好设置文件。这些文件经常被锁定、正在写入、通过云端同步，或被防病毒软件占用。如果未能读取，检查结果会显示无法检查，并说明扩展程序可能已经存在。这并不是委婉地说它缺失了；解决方法是再次运行 gsc_doctor()（如果浏览器正在运行，请先关闭），而不是重新安装一个已经在原处的扩展程序。同样的区别也适用于 gsc_detect_browsers，其中的 has_extension 字段有三种取值：true 表示存在，false 表示已读取所有偏好设置文件且其中没有该扩展程序，null 表示无法执行检查。

Microsoft Edge 可能会报告 Microsoft 账号，而非预期的 Google 账号。 Edge 会将已登录账号的地址存储在与 Chrome 用于存储 Google 账号的相同文件和相同键中，但默认情况下，它会使用 Microsoft 身份登录配置文件。磁盘上的信息无法区分二者。因此，对于 Edge 配置文件，找到一个地址并不能证明已登录 Google 账号；即使你的 Microsoft 地址恰好与 Google 地址相同，看似确认匹配的结果也并未得到确认。这些工具会谨慎处理，而不会直接断言：Edge 配置文件会报告“无法确认此配置文件的 Google 登录状态”。在依赖该结果之前，请自行检查。Brave、Vivaldi、Opera 和纯 Chromium 都不会记录 Google 账号，因此会出于不同原因给出保留判断：没有可读取的信息。

扩展程序 ID 发生变化意味着需要重新配对，而非出现故障。 该扩展程序未附带 manifest key，因此 Chromium 会根据加载路径的绝对路径计算哈希并生成 ID。只要提取目录保持不变，该 ID 就会保持稳定；如果目录移动，ID 就会变化：例如升级时配置目录被迁移、使用了不同的 GSC_MCP_HOME，或迁移到新计算机。ID 变化后，扩展程序检查就无法再识别已加载的副本，并会将其报告为未安装。这既不代表出现故障，也不代表数据损坏；解决方法是按照步骤 4，从新文件夹重新加载未打包的扩展程序。

绿色的 extension 检查表示已注册，而非正在运行。 它表示该扩展程序已按相应版本加载到该配置文件中。其 MV3 后台服务工作线程是否处于活动状态是另一个问题，只有桥接服务才能给出答案：提交时，它会等待连接；如果没有收到连接，就会唤醒已被回收的工作线程；如果仍然无效，则会以 extension_not_connected 失败。gsc_doctor 仍只报告注册状态。

开发

.venv/Scripts/python -m pip install -e ".[dev]"   # POSIX: .venv/bin/python
.venv/Scripts/python -m pytest -v

架构

gsc_core 是一个独立引擎，不依赖 MCP，因此 MCP 服务、命令行或未来的桌面应用都可以直接驱动它，无需改动。

模块	职责
gsc_core/paths.py	各平台上的文件存放位置
gsc_core/runlog.py	将日志写入 stderr 和文件 — 绝不写入 stdout，因为 MCP 将其保留用于 JSON-RPC
gsc_core/store.py	SQLite：站点、URL、提交记录、任务、配额时段
gsc_core/quota.py	按资源属性滚动统计时段用量
gsc_core/gauth.py	使用 PKCE S256 的 OAuth 2.0、强化的令牌存储、刷新
gsc_core/config.py	可由用户调整并带有验证的设置
gsc_core/browsers.py	已安装的 Chromium 浏览器，以及它们存放状态的位置
gsc_core/profiles.py	各浏览器中的配置文件，以及每个配置文件登录的 Google 账号
gsc_core/pairing.py	桥接扩展的解压位置，以及 Chromium 为其分配的 ID
gsc_core/bridge.py	浏览器扩展连接回来的 localhost WebSocket 服务
gsc_core/submit.py	按 URL 提交的循环：路由、原子配额预留、结果

隐私

为了告诉你该使用哪个浏览器配置文件，此工具会从你计算机上浏览器自己的文件中读取配置文件列表和已登录账号地址 — Local State 以及各配置文件的 Preferences / Secure Preferences。读取这些文件的另一个目的是查明桥接扩展是否已在该配置文件中加载，以及其版本。

这些读取完全在本地进行。地址仅在内存中使用，用于显示哪个配置文件登录了哪个账号，并且：

• 绝不会传输到任何地方，
• 此工具绝不会将其写入磁盘，
• 绝不会以任何级别写入日志 — 读取这些文件失败时，日志中只记录异常类型名称，正是为了避免地址或包含 Windows 用户名的路径出现在你可能会附在错误报告中的日志文件里。

此工具不会以写入方式打开这些文件。任何工具都不会返回地址，无论是单向还是反向 — 既不会返回在配置文件中找到的地址，也不会返回你自己的已授权地址。工具结果会被渲染到对话记录中，并由驱动该服务的 MCP 客户端保留；本项目无法控制这些内容，因此配置文件只通过浏览器和配置文件目录来标识，不包含其他信息。

有一条路径是例外，而且这是有意为之。当 gsc_setup 发现桥接扩展尚未加载时，其结果会包含扩展解压到的目录 — 在 Windows 上为 C:\Users\<your username>\AppData\Roaming\gsc-mcp\extension。在大多数计算机上，该路径包含你的操作系统账号名称。返回该路径是因为 Chrome 中的“Load unpacked”要求你选择这个确切的文件夹，而无法照着操作的设置说明并不能带来隐私保障。这是任何工具返回的唯一一条路径，只会出现在需要它的那个步骤中，并且绝不会写入日志。如果你不希望账号名称出现在对话记录中，请运行该步骤，然后清除对话记录。

已知不足

直言不讳，因为这些是审查者最应该首先关注的事项：

• 没有测试能证明 icacls 在 Windows 上确实应用了 ACL——Windows 测试只观察调用是否发生，因此 _harden 在那里即使什么都不做，测试套件也会通过。POSIX 对应实现现在会在每次推送时于 Linux 和 macOS 上执行，因此这个缺口仅存在于 Windows。
• 提交路径现在已提交过真实 URL，但测试套件仍无法证明这一点。 截至 2026-08-05，它已驱动真实浏览器、点击“请求编入索引”，并得到 Google 对请求的确认——在 Windows 11 上，使用 Chrome 和 Brave，历时数日、涉及多个资源，还曾让配额账本触及 Google 的真实拒绝。自动化测试套件实际运行的仍只有伪实现：关于扩展桥接、提交节奏、配额预留、运行循环和作业工作线程的每项断言，都是针对替身作出的。因此，“它能提交 URL”现在有手动日志作为依据，而非 CI；伪实现无法触及的状态仍是 docs/manual-smoke.md 中的提交检查。实际运行持续发现测试套件漏掉的缺陷；请假设它还没发现完。
• 登录路径现在已实际走通——一次，在一台机器上（Windows 11、Chrome、Python 3.13、2026-08-04），使用一个拥有九个资源的账号。docs/manual-smoke.md 的步骤 1-8 均已通过。在一个平台上跑一次不等于覆盖充分：它发现了整个自动化测试套件都漏掉的两个缺陷，这正是应在 macOS 和 Linux 上再次运行的理由，而不是盲目信任它。
• doctor 无法检测过期的扩展构建版本，也不再假装可以。 Chromium 不会为未打包的扩展记录清单快照——而未打包是此桥接唯一的安装方式——因此根本无法从磁盘读取浏览器实际运行的版本。现在检查会报告磁盘上的版本，并说明已加载的版本无法读取，而不是把前者冒充成后者。要解决这个问题，需要扩展通过桥接报告 chrome.runtime.getManifest().version，这属于协议变更，会推迟到桥接经过真实提交验证之后再做。
• 桥接端口默认是 8765，两个运行实例无法共用。 第二个 gsc-mcp 进程，或任何已占用该端口的其他程序，都会绑定失败——现在运行会在几秒内失败，并指出端口和解决办法，而不是等完整连接超时后才归咎于扩展。更改端口（配置中的 bridge_port）需要在扩展的选项页面设置相同端口；两者必须配对，不会自动发现。
• macOS 和 Linux 上的浏览器检测迄今只针对测试样本运行过，在这里和 CI 中都从未在真实硬件上运行过。在 Mac 或 Linux 机器上首次运行烟雾测试清单的人，实际上就是在进行这项测试。
• gsc_detect_browsers 目前在所有真实机器上都会将 matches_authorised_account 报告为 null。这个标志会从存储的令牌中读取 account_email 键，但没有任何代码写入它：当前的 scope 集不会返回身份声明，授权步骤也不会记录授权账号。相关管线正确但未启用。应将此字段视为“未知”，而非“不匹配”。
• extension 检查报告的是扩展是否已注册，而不是它是否正常工作。只有桥接才能知道 MV3 工作线程是否存活，而且只有在提交时才能确认。
• 已发布的软件包在 PyPI 上的名称是 gsc-indexer-mcp，不是 gsc-mcp——后者属于另一位作者的无关项目，安装它会得到对方的服务，而不是本项目的服务。两个发行渠道在一个实质方面也有所不同：GitHub 发行版 wheel 内含本项目的 OAuth 客户端，而 PyPI wheel 则有意不包含（把秘密放在公共索引上会导致秘密被撤销），因此 PyPI 安装会在首次调用 gsc_setup() 时从 client 发行资源下载客户端。这两条路径都经过了验证，但它们并不相同；其中一条路径上的缺陷不会在另一条路径上显现。
• mcp 固定为 >=2.0,<3。服务是按 mcp 2.0 的 MCPServer API 编写的——1.x 使用的名称是 FastMCP，两种 API 形态互不兼容，因此本软件包现在会与仍要求 mcp<2 的任何依赖发生硬性冲突（这与旧版 <2.0 上限造成的冲突正好相反）。

贡献

我们真诚欢迎各种贡献——问题反馈、拉取请求、错误报告、文档修正，所有贡献都欢迎。请从 CONTRIBUTING.md 开始。适合新手的问题见“已知差距”中列出的 CI 检查项。

目前你能做的最有价值的贡献，是在非 Windows 设备上提交一份错误报告。 这里的所有内容都只有一个人在一种操作系统上手动测试过；请参阅已知差距。

• 报告错误 · 请求新功能
• 安全政策 — 如有涉及令牌、OAuth 或本地桥接的事项，请私下报告
• 行为准则

许可证

Functional Source License 1.1 with an Apache 2.0 future grant（FSL-1.1-ALv2）。

简单来说：你可以使用、修改、参与贡献，也可以将其用于客户项目——但不要基于它销售竞品。 每个版本都会在发布两年后转换为 Apache 2.0，因此这里的任何内容都不会被永久封存。