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「帮我看看这个页面…」即可。

Related MCP server: BrowserPilot

MCP 工具

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:模拟扩展应答(开发测试用)

故障排查

License

MIT