Browser Bridge

AI ↔ 浏览器控制桥:把浏览器变成 MCP 工具集。任何 MCP 客户端(AI 程序)通过标准 MCP 协议调用 browser_snapshot / browser_click / browser_type 等工具,在真实浏览器里操作网页。

• 支持任意 MCP 客户端:Claude、codex、自定义 agent、curl
• 默认跟随模式:AI 自动控制你当前激活的标签页,零配置
• 真实浏览器,非 headless:登录态、验证码(提示你手动)、反爬特征自然

快速开始

1. 下载

从 Releases 下载一个压缩包:

• browser-bridge-<platform>-<arch>.zip — 按你机器的平台选

解压到任意目录(下文用 <DIR> 表示),目录内含 browser-bridge/(扩展)、browser-bridge-host、install-host.sh(Windows 为 install-host.ps1)。

2. 加载扩展

1. 打开 chrome://extensions
2. 右上角打开开发者模式
3. 点「加载已解压的扩展程序」,选择解压后的 browser-bridge/ 目录

3. 安装 host

macOS / Linux:

cd <DIR>
./install-host.sh         # Windows(PowerShell): .\install-host.ps1

运行后会列出检测到的浏览器,回车安装到全部,或输入序号选特定浏览器;也支持参数直接指定:

./install-host.sh --all      # 安装到全部浏览器
./install-host.sh --chrome   # 只装 Chrome(--chromium / --edge 同理)

扩展 ID 已内置固定,无需手动填写;若你的扩展 ID 不同,可追加传参:./install-host.sh <你的扩展ID>。

若浏览器已打开,安装后请完全退出并重启浏览器。

4. 使用

任意 MCP 客户端连接:

MCP server: http://127.0.0.1:1234/mcp

端口被占时自动 +1,实际端口看扩展 popup(已连接 · MCP端口 xxxx)或 ~/.browser-bridge/port。

codex 配置示例(~/.codex/config.toml):

[mcp_servers.browser]
url = "http://127.0.0.1:1234/mcp"

之后告诉 AI「帮我看看这个页面…」即可。

MCP 工具

工具	参数	说明
browser_control_status	—	查询控制目标与连接状态
browser_list_tabs	—	列出所有标签页
browser_use_tab	tabId(-1 回跟随)	固定/切换控制目标
browser_new_tab	url?	新建标签页并立即跳转(缺省空白页)
browser_close_tab	tabId?	关闭标签页(缺省关受控页,自动回跟随)
browser_activate_tab	tabId	激活标签页给用户看,不改控制目标
browser_duplicate_tab	tabId?	复制标签页(缺省复制受控页)
browser_pin_tab	tabId?, pinned?	固定/取消固定标签页
browser_snapshot	—	可交互元素快照(ref 编号+坐标)
browser_extract	format?(markdown|html|raw)	提取正文;对话页(ChatGPT/Gemini)按问答轮次组装;format=html 返回净化 HTML,raw 返回原始 body HTML
browser_screenshot	—	可视区截图(dataUrl,视觉理解复杂布局)
browser_url	—	查询当前控制页 URL 与标题(轻量)
browser_click	ref, button?	点击
browser_dblclick	ref	双击
browser_type	ref, text, clear?	输入(兼容 React 受控输入)
browser_form_fill	fields[]	批量填写多个字段
browser_press / browser_key	key, modifiers?	按键(支持 ctrl/shift/alt/meta)
browser_select	ref, value	下拉框
browser_scroll	dir, amount?, ref?	滚动
browser_hover	ref	悬停
browser_highlight	ref	高亮元素 1s(用户可见 AI 操作位置)
browser_drag	fromRef, toRef	HTML5 拖拽
browser_goto	url	跳转到指定 URL
browser_back	—	浏览器后退
browser_refresh	—	刷新页面
browser_wait_for	ms 或 selector 或 text(三选一,不可组合)	等待:定时(ms≤60s),或等元素出现,或等页面文本出现(UI 条件最多 5s)

AI 自行编排:snapshot → 决策 → 操作 → 再 snapshot,直到任务完成。

控制模式

• 跟随模式(默认):控制你当前激活的标签页,切 tab 即切目标
• 固定模式:锁定某个标签页(切换不跟随);popup 一键固定/取消,或 AI 调 browser_use_tab

工具栏图标徽标:无 = 跟随中;AI 琥珀 = 已固定;! 红 = 连接异常。

架构

任意 MCP 客户端
   │ MCP (Streamable HTTP, 127.0.0.1:1234/mcp)
browser-bridge host(单进程 = MCP ↔ 帧协议翻译器)
   │ native messaging(stdin/stdout 帧)
Chrome 扩展
   ├─ background:转发、目标解析、保活、状态徽标
   └─ content script:快照 / 执行

MV3 扩展无法监听端口,native host 是唯一通道(Chrome 官方 DevTools MCP 同构)。

从源码构建(开发者)

需要 bun:

bun install
bun run build                    # 当前平台 host + 扩展
./scripts/install-host.sh        # 注册 host(默认内置扩展 ID)
bun run scripts/build.ts --all   # 交叉编译全部平台 + 发布包(发布用)
bun test                         # 单元 + MCP API 集成测试(无需浏览器)

配置

• BROWSER_BRIDGE_PORT:MCP 初始端口(默认 1234,被占自动 +1)
• BROWSER_BRIDGE_MOCK=1:模拟扩展应答(开发测试用)

故障排查

现象	原因	解决
popup 显示「host 未连接」	未安装 host / 浏览器未重启	运行 install-host,完全退出浏览器重开
Invalid native messaging host name	host 名含连字符(旧版本)	更新到新版(host 名 com.browserbridge)
扩展 ID 不匹配	用旧版 manifest 加载	重新下载扩展,或 install-host 传参 install-host.sh <你的ID>
MCP 连不上	host 未运行	先打开浏览器+扩展(host 由 Chrome 拉起)
目标标签页不可达	页面未就绪/不是 http(s)	等页面加载,或用 browser_use_tab 固定

License

MIT