Browser Bridge

AI ↔ Puente de control del navegador: convierte el navegador en un conjunto de herramientas MCP. Cualquier cliente MCP (programa de IA) puede invocar 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, agentes personalizados, curl

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

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

Inicio rápido

1. Descargar

Descarga un paquete 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/ (la extensión), browser-bridge-host e install-host.sh (en Windows, install-host.ps1).

2. Cargar la extensión

1. Abre chrome://extensions

2. Activa el modo de desarrollador en la esquina superior derecha

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

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 instalarlo en todos, o introduce un número 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 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 estaba abierto, ciérralo por completo y reinícialo después de la instalación.

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 muestra 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, solo dile a la IA: «Ayúdame a ver esta página…».

Related MCP server: BrowserPilot

Herramientas MCP

La IA se orquesta por sí misma: snapshot → decisión → acción → nuevo snapshot, hasta completar la tarea.

Modos de control

• Modo de seguimiento (predeterminado): controla la pestaña activa actual; cambiar de pestaña cambia el objetivo

• Modo fijo: bloquea una pestaña concreta (el cambio de pestaña no lo sigue); desde el popup se puede fijar/cancelar con un clic, o la IA puede llamar a browser_use_tab

Insignia del icono de la barra de herramientas: sin insignia = en modo de seguimiento; 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 host nativo es el único canal (misma estructura que el MCP oficial de DevTools 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 inicial de MCP (por defecto 1234, si está ocupado se incrementa automáticamente en +1)

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

Solución de problemas

Licencia

MIT