Browser MCP

Expón tu navegador Chrome/Edge como herramientas MCP para cualquier agente de IA. Una extensión de Chrome (Manifest V3) actúa como el propio servidor MCP: se conecta a un code-mcp-gateway y responde a las peticiones MCP en el acto, sin necesidad de servidor local. Habla el mismo protocolo JSON-RPC que code-mcp, por lo que se integra en configuraciones de agentes existentes.

Cómo funciona

flowchart LR
  subgraph Agent["Agent side"]
    A["MCP client / AI agent"]
  end

  subgraph Gateway["code-mcp-gateway (Cloudflare Worker)"]
    G["wss://code-mcp.tuanm.dev/ws/<id>"]
  end

  subgraph Browser["Your browser"]
    E["Extension (MV3)<br/>service worker = MCP server<br/>offscreen = WS bridge"]
    P["Page (content script)"]
  end

  A -- "MCP JSON-RPC" --> G
  G -- "register / keepalive /<br/>forward requests" --> E
  E -- "CDP / tabs / scripting" --> P

El popup solicita un ID de dispositivo y un Token; la extensión se conecta directamente a la puerta de enlace (registro, keepalive cada 25 s, watchdog de 75 s, reconexión con retroceso exponencial y jitter) y atiende initialize / tools/list / tools/call en el acto. Cualquier agente que pueda alcanzar la puerta de enlace puede controlar el navegador.

Un servidor local opcional (browser-mcp.ts) añade un almacén de archivos (file_read, descargas/subidas grandes) y un endpoint HTTP MCP local simple. Consulta Servidor local.

Inicio rápido

Chrome o Edge >= 111. Bun >= 1.1 solo es necesario para el servidor local o las herramientas de desarrollo: la extensión funciona de forma independiente.

1. Carga la extensión. Abre chrome://extensions, activa el modo de desarrollador, haz clic en Cargar descomprimida y selecciona packages/browser-extension. (O ejecuta bun browser-mcp.ts y descarga el zip desde http://127.0.0.1:7777/extension).

2. Conéctate. Haz clic en el icono de la barra de herramientas (la marca MCP se vuelve verde al conectarse). Introduce el ID de dispositivo y el Token de la puerta de enlace y haz clic en Conectar. El popup mostrará Conectado (gateway).

3. Úsala. Apunta cualquier cliente MCP a tu dispositivo de la puerta de enlace. La extensión responde a tools/list con 47 herramientas.

El token debe coincidir con el configurado para este dispositivo en la puerta de enlace. La puerta de enlace lo reenvía con cada petición y la extensión lo verifica. Si lo dejas vacío, cualquiera que llegue a la puerta de enlace podrá controlar el navegador.

Servidor local

Solo es necesario para el almacén de archivos (file_read, descargas/subidas > 512 KB) o un endpoint HTTP MCP local:

bun browser-mcp.ts                  # http://127.0.0.1:7777/mcp
bun browser-mcp.ts --token <s>      # require auth on /mcp + /files

Con el servidor en marcha, el popup también entrega el ID + Token al enlace de la propia puerta de enlace del servidor; sin él, la extensión sigue funcionando directamente. Los clientes locales usan http://127.0.0.1:7777/mcp; consulta mcp-client.example.json (añade "headers": { "Authorization": "Bearer <token>" } si ejecutas con --token). Verifícalo con: curl -s http://127.0.0.1:7777/health.

Acceso remoto mediante code-mcp-gateway

• Directo (predeterminado). Introduce el ID + Token en el popup; la extensión sirve MCP por sí misma. Sin servidor local.

• Enlace del lado del servidor. Con el servidor local, el popup se conecta a wss://code-mcp.tuanm.dev/ws/<id> y el servidor responde a MCP a través de HTTP.

• CLI (puerta de enlace personalizada):

  bun browser-mcp.ts --gateway <domain> --token <s> --id <device-id>

  Mismo protocolo que el modo directo. Usa el mismo --token en el dispositivo de la puerta de enlace; nunca ejecutes el modo puerta de enlace sin uno. Establece BMCP_GATEWAY_DOMAIN para sobrescribir el host de puerta de enlace predeterminado del popup.

Herramientas (47)

Detección de elementos con el sistema @ref: snapshot devuelve un árbol de elementos interactivo con marcadores [ref=eN]; cada herramienta de interacción acepta la ref o un selector CSS (las refs se guardan en caché y se resuelven automáticamente; las refs obsoletas devuelven el error "run snapshot again").

• Descubrimiento — snapshot, find (role/name/text/label/placeholder/title/testid/selector), get, is

• Interacción — click, dblclick, type, fill, check, uncheck, select, hover, focus, press, drag, scroll, upload

• Navegación — navigate, reload, back, forward, close, tabs, window

• Lecturas de página — extract, execute, screenshot (bloque de imagen), pdf, wait, highlight

• Estado y depuración — store, cookies, storage, console, errors, network, status, file_read

• Emulación y control — emulate, set (viewport/device/geo/offline/headers/media), perms, auth, dialog, frames, touch, download

La captura de consola/errores/red comienza en la primera llamada (perezosa), así que recarga o navega después de activarla para capturar tráfico. Atrás/Adelante usan el historial de navegación de CDP. Ejecuta curl -s -X POST http://127.0.0.1:7777/mcp -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' para ver los esquemas completos.

Banderas

Seguridad

• Restringido por origen. /browser/ws solo acepta orígenes chrome-extension://; /mcp y /files/* rechazan orígenes de navegador distintos de localhost: un sitio web malicioso no puede controlar tu navegador a través de localhost (CSRF). Los clientes MCP nativos (sin cabecera Origin) no se ven afectados.

• --token protege /mcp y /files/* (?token= o Bearer); --extension-token añade un secreto que la extensión debe presentar en el puente.

• Los ID de archivo son hex aleatorios de 12 caracteres validados con un patrón estricto; los nombres de archivo de subida se sanean. Límites de tamaño: subidas de 500 MiB, capturas de pantalla de 8 MiB en línea.

• chrome.debugger muestra la barra de información amarilla mientras está adjunto (señal de consentimiento); perms/cookies usan API sin depurador cuando es posible.

• Se vincula a 127.0.0.1 de forma predeterminada; vincularse a 0.0.0.0 sin --token muestra una advertencia.

Tiempos de espera

Comandos del puente: 30 s por defecto, 60 s para navigate/execute/wait_for, 120 s para download/file_upload, con un tope de 120 s en local y 55 s en modo puerta de enlace (la puerta de enlace anula los reenvíos después de 60 s). Las herramientas aceptan bridge_timeout para sobrescribirlo.

Desarrollo

bun run check   # syntax-check server + scripts + extension JS
bun run test    # mock-extension + mock-gateway E2E suite
bun run build   # rebuild dist/browser-extension.zip
bun browser-mcp.ts  # run the server