Chrome 浏览器控制

用于 stdio MCP 主机的本地 Chrome 配置文件控制。

该项目通过一个连接到环回 WebSocket 代理的 Manifest V3 Chrome 扩展，暴露浏览器控制 MCP 工具。配置您的 MCP 主机，使用与扩展中输入的相同配对令牌启动 stdio 适配器。

仓库：https://github.com/vkongv/chrome-browser-control

前提条件

• Node.js 18+

• Google Chrome

Related MCP server: Tabrix

安装与设置

推荐路径：先安装 CLI，然后运行设置。

npm install -g chrome-browser-control
# or, without a global install:
npx -y chrome-browser-control setup

CLI 安装为 cbctl（推荐短名称）以及 chrome-browser-control。

cbctl setup
cbctl start
cbctl doctor

setup 写入 ~/.chrome-browser-control/config.env（配对令牌 + 端口），将解压后的扩展复制到 ~/.chrome-browser-control/extension，并打印 MCP 主机代码片段。不要提交该目录。

代理技能（独立于 npm）

skills/chrome-browser-control/ 下的运行时代理技能不包含在 npm 包中。安装 CLI 后，如果您的代理主机使用技能，请从本仓库（或 skills.sh）获取该技能。

CLI 命令（cbctl 或 chrome-browser-control）：

从 git 检出（贡献者）：

git clone https://github.com/vkongv/chrome-browser-control.git
cd chrome-browser-control
npm install
npm run build
node dist/cli/main.js setup

仓库本地 npm run broker / npm run mcp 仍可用于针对 TypeScript 源码进行开发（可选的仓库 .env.local）。

环境变量

• CHROME_BROWSER_CONTROL_TOKEN — 必需。由代理、MCP 适配器和扩展弹出窗口共享的高熵配对令牌。

• CHROME_BROWSER_CONTROL_PORT — WebSocket 代理端口（默认 8765）。

• CHROME_BROWSER_CONTROL_HOST — 代理的环回主机（默认 127.0.0.1）。

• CHROME_BROWSER_CONTROL_EXTENSION_ID — 可选。将代理固定到一个已安装的扩展 ID。

• CHROME_BROWSER_CONTROL_AUTOLOAD — 可选。设置为 1 以便 mcp 在无法连接代理时自动启动一个（恢复）。正常使用请优先使用 cbctl start。

• CHROME_BROWSER_CONTROL_DISABLE_LOCAL_ENV — 可选。设置为 1 以跳过加载仓库 .env.local。

用户配置位于 ~/.chrome-browser-control/，并在任何仓库 .env.local 之前加载。进程环境变量始终优先。

MCP 仅附加默认：cbctl mcp 连接到一个已运行的代理。请先使用 cbctl start 启动代理。如需恢复，请使用 cbctl mcp --autoload 或 CHROME_BROWSER_CONTROL_AUTOLOAD=1。

加载扩展

1. 使用您希望 MCP 工具控制的配置文件打开 Chrome。

2. 转到 chrome://extensions。

3. 启用开发者模式。

4. 点击“加载已解压的扩展程序”。

5. 选择 ~/.chrome-browser-control/extension（由 setup 打印）。编辑源码的贡献者可以改为加载仓库中的 extension/。

6. 打开 Chrome 浏览器控制扩展弹出窗口。

7. 保持桥接 URL 为 ws://127.0.0.1:8765，除非您更改了本地端口。

8. 粘贴生成的配对令牌。

9. 添加允许的来源，例如 https://example.com、http://localhost:3000，或 * 以允许所有正常的 http:// 和 https:// 页面。

10. 点击“保存并重新连接”。

扩展可能会请求这些允许来源的主机权限。拒绝该请求将阻止这些来源的页面操作。

使用 * 对于本地开发很方便，但它会将当前 Chrome 配置文件中的每个正常网页暴露给 MCP 工具。当您只需要少数几个站点时，请优先使用显式来源。通配符模式还会请求可选的 <all_urls> 主机权限，以便 Chrome 允许通过 chrome.tabs.captureVisibleTab 进行可见视口截图；后台在捕获前仍会阻止非 http(s) URL 和不允许的来源。

MCP 主机配置

将 cbctl setup（或 mcp-config）中的代码片段粘贴到 Cursor、Claude Desktop、Codex 或其他 stdio MCP 主机中。要稍后再次打印特定主机的配置：

cbctl mcp-config --host cursor
cbctl mcp-config --host claude
cbctl mcp-config --host codex
cbctl mcp-config --host yaml

MCP 服务器键是 chrome_browser_control。适配器命令是可安装的 CLI（推荐 cbctl），带有 args: ["mcp"] — 而不是针对 server/index.ts 的 tsx。

YAML 风格示例：

mcp_servers:
  chrome_browser_control:
    command: "cbctl"
    args: ["mcp"]
    env:
      CHROME_BROWSER_CONTROL_TOKEN: "<generated-token>"
      CHROME_BROWSER_CONTROL_PORT: "8765"
    timeout: 60
    connect_timeout: 30

JSON 风格示例：

{
  "mcpServers": {
    "chrome_browser_control": {
      "command": "cbctl",
      "args": ["mcp"],
      "env": {
        "CHROME_BROWSER_CONTROL_TOKEN": "<generated-token>",
        "CHROME_BROWSER_CONTROL_PORT": "8765"
      }
    }
  }
}

如果 CLI 不在 PATH 中，请使用设置打印的 NPX 回退：npx 带有 args: ["-y", "chrome-browser-control", "mcp"]。

如果您的 MCP 主机使用配置文件，请将其保密并放在仓库之外。

验证

1. 启动代理：cbctl start

2. 运行设置检查器：cbctl doctor

3. 通过调用 browser_status 工具从您的 MCP 主机确认。准备就绪后，extension.status 和 ping.status 应反映实时的桥接连接，并且 extension.allowedOrigins 应显示您配置的范围。

工具

• browser_status：检查 MCP 适配器是否可以到达代理，以及 Chrome 扩展是否响应 ping。准备就绪后，extension.status 和 ping.status 反映实时的桥接连接（不是过时的断开连接默认值），extension.allowedOrigins 显示配置的范围（包括启用通配符模式时的 * (all http/https web origins)），extension.session 显示会话名称/声明的标签页，protocolVersion / features 确认已加载的解压扩展代码。协议版本 6 包含 document-targeting 功能标记。

• name_session：为状态/调试设置一个人类可读的会话名称。

• list_tabs：列出 URL 来源在扩展弹出窗口中允许的标签页。当所有打开的标签页都被过滤掉时，返回 { tabs: [], detail, hiddenTabCount, allowedOrigins? } 而不是一个空的 []。通配符模式在 allowedOrigins 中清晰标记。

• list_frames：使用 Chrome 的帧注册表列出允许标签页的当前帧文档。可操作的活跃 HTTP(S) 文档包含一个 documentId；策略阻止、主机权限拒绝、不受支持、围栏和非活跃行仅保留层次结构/状态，并编辑 URL 和文档标识。

• claim_tab：为此浏览器控制会话声明一个允许的标签页，并返回一个 sessionTabId。声明是路由状态，不是独占的浏览器锁。

• release_tab：通过 sessionTabId 或 tabId 释放声明，而不关闭标签页。

• finalize_tabs：释放会话的声明状态，而不关闭标签页。传递 keep 条目以保留交接/可交付声明。

• snapshot：返回允许文档的简化 DOM 快照。默认情况下，这是一个紧凑的自动化快照，包含简洁的可操作元素、文本预览（500 字符）、省略计数和区域摘要。传递 mode: "full" 以获取详细的元素元数据和 text 字段（默认 4000 字符）。传递 mode: "visible" 以获取视口/交集感知的元素，包含边界和滚动元数据。当您需要更多页面正文文本时，传递 textLimit（最多 100000）— 检查 textBytesOmitted 以查看内容是否被截断。

• visible_snapshot：snapshot({ mode: "visible" }) 的便捷工具。

• navigate：将活动标签页或指定的 tabId 导航到允许的 URL，然后在可能的情况下等待标签页完成加载。默认情况下，焦点不变（后台标签页保持后台；焦点标签页不会被停用）。仅当标签页必须变为可见时传递 active: true。如果加载超时，结果包含 pending: true 和 warning。支持加载等待后的 after 观察。

• click：通过快照引用在允许的标签页上点击元素。支持 after 观察。

• type：通过快照引用在允许的标签页上输入元素。类似密码的字段会被阻止，除非 force=true。支持 after 观察。

• scroll：通过 deltaX 和 deltaY 滚动允许的标签页。可选的 x/y 视口坐标会在找到可滚动元素时滚动该点下的元素。滚动不会分页快照文本 — 快照使用完整的 document.body innerText。在 snapshot 上提高 textLimit 而不是滚动拼接，除非页面延迟加载内容。支持 after 观察。

• query_elements：返回由 CSS 选择器、角色、文本和可见性过滤的元素的边界引用/角色/标签/边界。

• extract_elements：从 CSS 选择器中提取有边界的文本/HTML/链接/时间数据。HTML 提取会编辑密码/OTP/隐藏令牌属性值，并标记敏感项目而不是泄露秘密值。这是原始 JavaScript 评估的受支持替代方案。

• screenshot：将允许标签页的可见视口捕获为数据 URL。可选的 ref 或 bounds（+ padding）在捕获后裁剪；空的裁剪会在 captureVisibleTab 之前失败。未裁剪的响应省略裁剪字段。MV3 捕获仅限视口；非活动目标标签页可能在捕获前被激活。Chrome 需要 <all_urls> 或 activeTab 才能使用 captureVisibleTab；此扩展仅在通配符（*）模式下请求可选的 <all_urls>，因此通配符截图需要该弹出窗口授权。

• keypress：向页面分发常见的 DOM 键盘事件。MV3 下不保证浏览器/操作系统级快捷键。支持 after 观察。

• click_at：在视口坐标处分发鼠标事件。支持 after 观察。

• wait_for：等待有边界的选择器/文本/URL 子字符串条件，并返回匹配/超时证据。

• page_status：返回标题、URL、就绪/可见性状态、视口/滚动状态以及按发起者类型划分的资源计数。它不暴露请求头或响应体。

• console_logs：返回在内容脚本注入后捕获的有边界控制台日志。它无法看到更早的页面控制台历史。

• collect_scroll：滚动有限数量的步骤（设置 until 时有硬上限），每一步提取选定的元素，可选地通过 scroll 定位嵌套滚动容器，应用聚合项目上限（maxItems，默认 100），并可选择通过文本或 href 去重以用于延迟加载的 feed。可选的 until.noNewItemsForSteps / until.stopBeforeDatetime（ISO-8601；需要 includeTimes）设置 stoppedReason。结果包括省略/截断计数。支持 after 观察。

• perform_actions：在一次代理往返中运行最多 10 个顺序页面操作（click、type、scroll、keypress）。在第一步错误时快速失败；仅当每一步都成功时才运行终端 after 观察。坐标点击请使用单工具 click_at。步骤不能携带 after、tabId 或 sessionTabId。

帧文档定位

DOM/内容工具接受由 list_frames 返回的可选 documentId。省略它保留现有行为，并针对每个操作的当前顶部文档。提供它则选择该确切文档：如果 iframe 导航、消失、移动到另一个标签页、变得不受支持或失去访问权限，操作将失败，而不是回退到顶部帧或使用相同 frameId 的替换帧。

每个内容结果都携带后台验证的 documentId、frameId、isTopFrame 和 coordinateSpace。顶层框架坐标使用 tabViewport；iframe 的 visible_snapshot 边界、click_at 和坐标滚动使用 frameViewport。iframe 局部边界不能传给截图裁剪，因为 screenshot 仍然是仅限标签页视口的工具。navigate、screenshot 和 list_frames 仅接受标签页目标；perform_actions.documentId 适用于整个批次，不能被单个步骤覆盖。

文档失败会保留以下前缀之一，包括在批次步骤错误和 after 失败中：DOCUMENT_STALE:、DOCUMENT_POLICY_DENIED:、DOCUMENT_HOST_PERMISSION_DENIED: 或 DOCUMENT_UNSUPPORTED:。V1 仅支持活动的 HTTP(S) 最外层/子框架文档。它有意排除 about:blank、about:srcdoc、blob:、data:、源回退框架、iframe 导航，以及 iframe 到标签页的截图坐标转换。

先动作后观察

动作工具 navigate、click、type、scroll、keypress、click_at、collect_scroll 和 perform_actions 接受可选的 after 对象。扩展在将基础动作发送到内容脚本之前移除 after，然后按以下固定顺序运行请求的观察：waitFor、snapshot、pageStatus。响应是基础动作结果加上包含观察结果的 after 对象。

对于 perform_actions，after 仅适用于整个批次：单个步骤不能包含 after，并且当任何步骤失败时，收尾观察会被跳过。部分批次失败返回带有 failedIndex 和 completedCount 的结构化步骤结果，同时保留网桥级别的成功状态，以便智能体可以检查负载。

{
  "ref": "h12",
  "after": {
    "waitFor": { "selector": ".results", "timeoutMs": 5000 },
    "snapshot": { "mode": "visible", "limit": 40 },
    "pageStatus": true
  }
}

after.waitFor 必须至少包含 text、selector 或 urlIncludes 之一；timeoutMs 是可选的，上限为 20000，以便完整的先动作后观察链路保持在默认 broker 请求超时内。after.snapshot 可以为 true（使用默认快照选项），也可以是包含 mode、textLimit 和/或 limit 的对象。无效的 after 请求会在基础动作运行之前被拒绝。

如果基础动作成功但某个 after 观察失败，响应仍然包含基础动作结果，并将 after 设置为 { "ok": false, "error": "..." }。

快照模式与 Refs

默认的紧凑快照旨在减少模型上下文占用，同时保留浏览器自动化能力。紧凑快照示例如下：

{
  "title": "Example Domain",
  "url": "https://example.com/",
  "mode": "compact",
  "elements": [{ "ref": "h1", "role": "link", "label": "Learn more" }],
  "omittedElements": 0,
  "textPreview": "Example Domain ...",
  "textBytesOmitted": 0,
  "regions": []
}

仅当需要遗留的详细元素元数据时才使用完整模式：

{ "mode": "full", "tabId": 123 }

对于视口相关的工作、虚拟化页面和点击坐标规划，请使用可见模式：

{ "mode": "visible", "sessionTabId": "tab-1" }

要读取较长的页面内容（例如 API 文档），请提高 textLimit，而不要使用 broker 脚本或 CDP 变通方法：

{ "mode": "full", "textLimit": 100000, "tabId": 123 }

紧凑模式同样遵循 textLimit；正文文本通过 textPreview 返回（紧凑模式下没有 text 字段）。当 textBytesOmitted 大于零时，请增大 textLimit，或者仅在内容于首屏下方懒加载时才滚动页面并重新快照。

Refs 是按文档的内存 ID（h...），根据元素身份分配，而非输出顺序。它们在同一个文档内的 DOM 插入/重排中保持稳定，click / type 通过内容脚本的 ref 存储进行解析。Refs 在不同框架文档之间可能冲突，因此请保留结果的 documentId，并在后续 iframe 动作中传入它。导航到不同页面会加载新文档，因此旧的 refs 会按预期干净地失败；在导航或重大页面更改后请重新获取快照。ref 存储会剪除已断开、已过期和超容量的条目，并移除过期的 data-cbc-ref 属性，从而避免被剪除的 refs 被意外复用。

标签页会话

在多步骤浏览器操作之前，请优先使用 claim_tab：

{ "tabId": 123 }

返回的 sessionTabId 可以传给 snapshot、navigate、click、type、scroll、query_elements、extract_elements、screenshot、wait_for 及相关页面工具。如果会话有当前认领，则没有显式 tabId 或 sessionTabId 的页面动作会路由到该认领。如果不存在认领，则保留旧的活动标签页回退机制。

认领仅是建议性的 MCP 路由状态。它们不会阻止用户更改、关闭或导航标签页。任务完成时请使用 release_tab 或 finalize_tabs；这两个工具都不会关闭浏览器标签页。

开发检查

npm test
npm run build
cbctl doctor
# or: node dist/cli/main.js doctor
npm run benchmark:compact-snapshots
npm audit

npm run benchmark:snapshots 是同一个紧凑 vs 完整基准测试的别名。该基准会打印紧凑字节数、完整字节数和缩减百分比；在密集测试夹具上，紧凑模式应至少小 50%。

编辑 extension/ 下的文件后，在运行浏览器 e2e 检查之前，请在 chrome://extensions 页面上重新加载已解压的扩展。在 adapter/服务器更改后，还要重新构建并重启 MCP 主机。过期的已加载后台服务工作线程或工具目录可能会继续提供旧行为；当双方都是最新版本时，browser_status 应报告 adapter.registeredToolCount: 24、扩展协议版本 6 和 document-targeting 特性标记。

局限性

• 这是一个使用共享本地令牌的原型，不是多用户身份验证。

• 浏览器工具调用在 broker 处全局串行化。

• 内容脚本使用 DOM 快照，而不是完整的 Chrome 无障碍树。

• Refs 是文档作用域内的内存句柄。在导航、重新加载、重大 DOM 更改或过期 ref 错误之后，请重新运行 snapshot。

• 可见截图仅限视口。捕获非活动标签页可能会激活它，因为 Chrome MV3 捕获的是窗口中的可见标签页。

• Chrome 截图捕获需要 <all_urls> 或 activeTab。本项目仅将可选的 <all_urls> 作为主机权限请求，用于通配符截图。如果 screenshot 报告缺少此权限，请在 manifest 更新后重新加载扩展，打开弹窗、保存设置并同意权限提示。

• keypress 和 click_at 使用 DOM 事件，而非 CDP 输入分发。它们对页面处理程序很有用，但可能不会触发特权浏览器快捷键或每个框架特定的输入路径。

• 控制台日志仅在内容脚本注入后被捕获，并且数量有限。

• 资源摘要仅是来自 Performance API 的计数；请求头、响应体、cookie、存储、历史记录、书签和下载内容有意不公开。

• 浏览器历史记录、书签、下载和 cookie 工具有意不公开。

安全

• 不接受默认令牌。为 broker 和 MCP adapter 将 CHROME_BROWSER_CONTROL_TOKEN 设置为高熵、URL 安全的值，然后将相同的值粘贴到扩展弹窗中。

• broker 仅绑定到回环主机：127.0.0.1、localhost 或 ::1。

• 扩展仅连接到 ws://127.0.0.1、ws://localhost 或 ws://[::1]，可带可选端口。

• 页面访问受弹窗中配置的允许来源限制。使用显式条目（如 https://example.com），或输入 * 以允许所有正常的 http:// 和 https:// 网页。配置范围之外的标签页和页面动作将被阻止。

• 允许来源检查在扩展后台进行，先于内容动作、截图和标签页认领。

• 类似密码和 OTP 的字段通过输入类型、自动完成、名称、ID、标签和占位符来检测。type 会阻止它们，除非 force=true。

• 可选的 CHROME_BROWSER_CONTROL_EXTENSION_ID 将 broker 固定到一个已安装的扩展 ID。

• MCP adapter 不支持 CDP 回退，因为它绕过了扩展配对。

切勿将 broker 绑定到非回环接口，也不要提交令牌、本地配置文件、日志或个人设置说明。

维护者发布

首次公开发布的 npm 版本是手动的。维护者遵循 docs/publish-checklist.md。不要为默认发布路径在 CI 中添加推送时自动发布或长期有效的 npm 令牌。