Browser Bridge

Puente AI ↔ control del navegador: convierte el navegador en un conjunto de herramientas MCP. Cualquier cliente MCP (programa de IA) invoca herramientas como browser_snapshot / browser_click / browser_type a través del protocolo MCP estándar para operar páginas web en un navegador real.

• Compatible con cualquier cliente MCP: Claude, codex, agente personalizado, curl

• Modo de seguimiento por defecto: la IA controla automáticamente tu pestaña activa actual, sin configuración

• Navegador real, no headless: sesión iniciada, captchas (te pide que los resuelvas manualmente), características anti-scraping naturales

Inicio rápido

1. Descarga

Descarga un archivo comprimido desde Releases:

• browser-bridge-<platform>-<arch>.zip — elige según la plataforma de tu máquina

Descomprímelo en cualquier directorio (en adelante <DIR>), que contendrá browser-bridge/ (extensión), browser-bridge-host, install-host.sh (en Windows, install-host.ps1).

2. Cargar la extensión

1. Abre chrome://extensions

2. Activa el modo desarrollador en la esquina superior derecha

3. Haz clic en «Cargar extensión descomprimida» y selecciona el directorio browser-bridge/ descomprimido

3. Instalar el host

macOS / Linux:

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

Al ejecutarlo se mostrarán los navegadores detectados; pulsa Enter para instalar en todos, o introduce el número de serie para elegir un navegador específico; también admite especificarlo directamente mediante argumentos:

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

El ID de la extensión ya está fijado internamente, no es necesario rellenarlo manualmente; si tu ID de extensión es diferente, puedes añadir el parámetro: ./install-host.sh <tu-ID-de-extensión>.

Si el navegador ya está abierto, después de la instalación sal por completo y reinicia el navegador.

4. Uso

Conecta cualquier cliente MCP:

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

Si el puerto está ocupado, se incrementa automáticamente en +1; el puerto real se puede ver en el popup de la extensión (Conectado · Puerto MCP xxxx) o en ~/.browser-bridge/port.

Ejemplo de configuración de codex (~/.codex/config.toml):

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

Después, dile a la IA «mira esta página…» y listo.

Related MCP server: Playwright MCP Server

Herramientas MCP

La IA se organiza sola: snapshot → decisión → acción → otro snapshot, hasta completar la tarea.

Modos de control

• Modo de seguimiento (por defecto): controla tu pestaña activa actual; al cambiar de pestaña cambia el objetivo

• Modo fijo: bloquea una pestaña concreta (no sigue al cambiar); fija/desfija con un clic en el popup, o la IA llama a browser_use_tab

Insignia del icono de la barra de herramientas: sin nada = siguiendo; AI ámbar = fijado; ! rojo = error de conexión.

Arquitectura

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

Las extensiones MV3 no pueden escuchar puertos; el native host es el único canal (misma arquitectura que el DevTools MCP oficial de Chrome).

Compilar desde el código fuente (desarrolladores)

Requiere bun:

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

Configuración

• BROWSER_BRIDGE_PORT: puerto MCP inicial (por defecto 1234, +1 automático si está ocupado)

• BROWSER_BRIDGE_MOCK=1: simula la respuesta de la extensión (para pruebas de desarrollo)

Solución de problemas

Licencia

MIT