Browser Bridge

AI ↔ Browser Control Bridge: Turn your browser into an MCP toolset. Any MCP client (AI program) calls tools like browser_snapshot / browser_click / browser_type through the standard MCP protocol to operate web pages in a real browser.

• Supports any MCP client: Claude, codex, custom agents, curl

• Default follow mode: AI automatically controls your currently active tab, zero configuration

• Real browser, not headless: login state, CAPTCHAs (prompts you to solve manually), natural anti-scraping characteristics

Quick Start

1. Download

Download one archive from Releases:

• browser-bridge-<platform>-<arch>.zip — choose based on your machine's platform

Extract to any directory (referred to as <DIR> below). The directory contains browser-bridge/ (extension), browser-bridge-host, install-host.sh (install-host.ps1 on Windows).

2. Load the Extension

1. Open chrome://extensions

2. Turn on Developer mode in the top-right corner

3. Click "Load unpacked" and select the extracted browser-bridge/ directory

3. Install the Host

macOS / Linux:

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

After running, it will list detected browsers. Press Enter to install to all, or enter a number to select a specific browser; you can also specify directly with arguments:

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

The extension ID is built in and fixed, no need to fill it in manually; if your extension ID differs, you can pass it as an additional argument: ./install-host.sh <your-extension-ID>.

If the browser is already open, fully quit and restart the browser after installation.

4. Usage

Connect with any MCP client:

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

If the port is occupied, it automatically increments by +1. The actual port is shown in the extension popup (Connected · MCP port xxxx) or in ~/.browser-bridge/port.

codex configuration example (~/.codex/config.toml):

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

After that, just tell the AI "take a look at this page..." and you're done.

Related MCP server: BrowserPilot

MCP Tools

AI orchestrates on its own: snapshot → decide → act → snapshot again, until the task is complete.

Control Modes

• Follow mode (default): controls your currently active tab; switching tabs switches the target

• Pinned mode: locks a specific tab (switching doesn't follow); pin/unpin with one click in the popup, or via AI calling browser_use_tab

Toolbar icon badge: none = following; AI amber = pinned; ! red = connection error.

Architecture

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

MV3 extensions cannot listen on ports, so the native host is the only channel (same architecture as Chrome's official DevTools MCP).

Building from Source (Developers)

Requires bun:

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

Configuration

• BROWSER_BRIDGE_PORT: MCP initial port (default 1234, auto-increments by +1 if occupied)

• BROWSER_BRIDGE_MOCK=1: mock extension responses (for development testing)

Troubleshooting

License

MIT