Chromium Bridge

Chromium Bridge

俄语版

连接基于 Chromium 的浏览器与 Claude Code 的桥接工具。官方的 “Claude in Chrome”扩展程序可在部分 Chromium 浏览器（Arc、Vivaldi 等）中连接，但自动化操作会卡住：它的工具基于标签页组 API， 而这些浏览器缺少该 API，或该 API 无法正常工作。此桥接工具仅使用普通的 chrome.tabs / chrome.scripting / chrome.debugger，因此适用于任何 可以加载扩展程序的 Chromium 浏览器。

演示

Claude 通过桥接工具操控浏览器——打开 Wikipedia、输入搜索内容， 然后进入文章页面：

架构

Claude Code ⇄ (stdio MCP) ⇄ server/index.mjs ⇄ (WebSocket, 127.0.0.1:8929) ⇄ extension in the browser
                                   ⇅ (WebSocket /chat)
                            chat panel (popup on the extension icon)

• extension/ — 一个 MV3 扩展程序：其服务工作线程与本地服务保持 WebSocket 连接，并执行服务发来的命令（标签页、导航、页面文本、屏幕截图、点击、填写表单）。点击图标会打开聊天面板（chat.html）——一个锚定在扩展程序图标上的弹出窗口。
• server/ — 一个 MCP 服务（stdio），向 Claude Code 提供 browser_* 工具，并将请求代理给扩展程序。它只接受来自 chrome-extension://… Origin 的 WS 连接——普通网页无法连接。它还提供 /chat 通道：面板消息通过 Claude Agent SDK 运行（使用 Claude Code 登录凭据进行身份验证），并使用相同的 browser_* 工具；内置工具（Bash、Read 等）已禁用。

聊天面板

相当于“Claude in Chrome”侧边栏的功能：点击扩展程序图标时打开一个弹出窗口（不使用 chrome.sidePanel——它并非处处受支持）。聊天可以查看浏览器内容：列出标签页、读取页面、截取屏幕截图和点击。

面板界面默认使用英语；当浏览器界面语言为俄语时，会自动切换为俄语。底栏中的语言选择器（Auto / English / Русский）可覆盖自动检测；页面上的徽标也会遵循相同的选择。

• 弹出窗口失去焦点（点击页面）时会关闭——这是浏览器的行为。对话上下文不会丢失：面板会记住 session_id，服务器会通过 Agent SDK 的 resume 恢复对话。弹出窗口关闭时正在进行的轮次会中断。
• 仅在服务器运行时有效（通常需要有一个活跃的 Claude Code 会话，并加载 chromium-bridge MCP）；否则面板会显示“Server unavailable”。
• 面板标题栏中的模型选择器：“Default”会采用 ~/.claude/settings.json 中的模型（即通过 /model 设置的模型；SDK 会话本身不会读取 Claude Code 设置，服务器会显式传递模型），其他选项则是强制指定的模型。切换后立即生效（setModel），并会记住选择。启动时指定模型： CHROMIUM_BRIDGE_CHAT_MODEL=sonnet（在服务器环境中设置）。 端口：CHROMIUM_BRIDGE_PORT（默认为 8929）——仅影响服务器端；扩展程序始终连接到 8929，因此更改端口时还需编辑 extension/sw.js 和 extension/chat.js 中的 WS_URL。
• 聊天记录：标题栏中的 🕓 按钮会列出以往的对话（存储在面板的 localStorage 中，最多保留最近 30 条）。
• 每轮结束后都会显示用量：本轮令牌数（↑ 输入，含缓存 / ↓ 输出）以及累计会话费用（$）（订阅费用为估算值，并非单独账单）。
• Agent 过程中截取的屏幕截图会直接显示在聊天流中（点击可展开）。这些截图不会保存到历史记录中（localStorage 容量有限）。
• 可以从剪贴板粘贴图片（在输入框中按 Cmd+V，每条消息最多 5 张）——模型可以看到图片；历史记录中只会保留一个标记。
• “Ask before acting”模式（输入框上方的复选框）：读取操作（标签页、文本、屏幕截图、控制台、网络）会直接进行，不会询问；更改操作——点击/输入/导航/JS/表单/关闭标签页/上传文件——则会等待用户通过 Allow / Deny 卡片作出选择。Agent 会看到拒绝结果并继续对话。切换后立即生效，无需重新创建会话（通过 Agent SDK 的 canUseTool）。

页面指示

当 Claude 操作某个标签页时（通过面板或 Claude Code）：

• 页面边缘会亮起橙色光效，并显示“✳ Claude is working…”徽标；最后一次操作后 2.5 秒渐隐；
• 虚拟光标（橙色箭头）会滑向操作点，并在点击时显示脉冲圆环；闲置 3.5 秒后消失。

屏幕截图中不会显示这两种指示，以免它们进入画面，并在使用坐标操作时干扰模型。对于无法注入脚本的页面（如 chrome://），会静默跳过指示。

安装

1. 扩展程序：克隆此仓库，打开 chrome://extensions（务必在正确的空间/配置文件中！），启用“Developer mode”，点击“Load unpacked”，然后选择 extension/ 文件夹。

2. MCP 服务——任选一种方式：

   • 通过 npm：claude mcp add -s user chromium-bridge -- npx chromium-bridge
   • 从克隆的仓库安装：cd server && npm install，然后运行 claude mcp add -s user chromium-bridge -- node "$(pwd)/index.mjs"。

   服务会在会话启动时加载——安装扩展程序后，请重启 Claude Code 会话。

   对于其他 MCP 客户端，将以下内容添加到配置中：

   {
     "mcpServers": {
       "chromium-bridge": {
         "command": "npx",
         "args": ["chromium-bridge"]
       }
     }
   }
   

3. 检查：browser_status 工具应返回 {"connected": true}。

工具

截至 v0.5。

工具	功能
browser_status	检查与扩展程序的连接
browser_tabs_list	列出标签页（id、标题、URL）
browser_tab_create / browser_tab_close	打开 / 关闭标签页
browser_navigate	导航至 URL；使用 back/forward 浏览历史记录
browser_page_text	获取页面标题、URL 和可见文本
browser_computer	通过 CDP 操作鼠标/键盘/截图：按坐标或 ref 点击、拖动、悬停、输入、组合键、滚动、缩放区域截图、等待
browser_read_page	获取带 ref id 的无障碍树（filter=interactive）
browser_find	按文本/角色查找元素，并返回 refs
browser_form_input	通过选择器或 ref 设置 input/textarea/select/checkbox/contenteditable 的值
browser_click	通过 CSS 选择器执行 DOM 点击（普通 .click()）
browser_upload_file	将文件放入 <input type="file">
browser_javascript	在页面上运行 JS（支持 await）
browser_console_messages	获取标签页控制台消息（支持正则表达式筛选）
browser_network_requests	获取标签页网络请求（支持正则表达式筛选）
browser_resize_window	设置窗口大小
browser_gif_start / browser_gif_stop	将标签页录制为 GIF → 文件；长时间录制时帧率会自动减半，以确保整个场景都能录入

除基本标签页操作外，其他操作都通过 chrome.debugger（CDP）执行： 截图不需要激活标签页；点击会生成真实的鼠标事件； 控制台/网络信息从首次通过 CDP 操作该标签页时开始收集。

限制

• 扩展程序仅存在于一个浏览器配置文件中——请将其安装在你要用于自动化操作的配置文件中。
• 服务运行期间，会定期 ping 以保持扩展程序的 service worker 处于唤醒状态。即使 worker 进入休眠（例如服务刚启动时），keepalive 闹钟也会在约 30 秒内将其唤醒；服务会等待最多 12 秒以重新连接，超时后报错。
• 信任模型：WS 服务监听 127.0.0.1，并拒绝 Origin 不是 chrome-extension://… 的连接，以阻止网页访问。它不会区分不同扩展程序，而且非浏览器本地进程可以伪造 Origin 标头——任何以你的用户身份运行的程序都被视为可信，这与大多数本地开发工具类似。不要在共享计算机上运行此桥接程序。
• 首次执行 CDP 操作时，浏览器会显示“Chromium Bridge started debugging this browser”提示栏——这是正常现象，调试器就是控制机制。关闭提示栏会断开调试器（下次操作时会重新连接）。
• 控制台/网络信息不会追溯记录——只会在首次操作标签页后开始记录。
• 端口 8929 由单个会话独占：第二个并行运行的 Claude Code 会话无法启动自己的 WS 服务（扩展程序会保留在第一个会话中）。

许可证

MIT