Browser Bridge

AI ↔ Browser Control Bridge: Turn your browser into an MCP toolset. Any MCP client (AI program) can call 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), anti-scraping characteristics are natural

Quick Start

1. Download

Download one archive from Releases:

• browser-bridge-<platform>-<arch>.zip — pick 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

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 via 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 extra argument: ./install-host.sh <your-extension-ID>.

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

4. Usage

Connect with any MCP client:

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

When 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 config example (~/.codex/config.toml):

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

Then just tell the AI "help me look at this page…".

Related MCP server: BrowserPilot

MCP Tools

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

Control Modes

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

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

Toolbar icon badge: none = following; amber AI = 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 if occupied)

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

Troubleshooting

License

MIT