mcp-chrome-server

MCP server que controla Chrome vía la Chrome Extension (MV3) usando la API chrome.debugger, con transporte dual stdio (para Claude Code) y Socket.IO (para el wrapper del ecosistema existente).

No requiere lanzar Chrome con --remote-debugging-port ni ningún flag especial: el control del navegador pasa siempre por la extensión, para poder usarse con un Chrome normal del usuario.

Requisitos

• Node.js 20+
• Extensión extension/ cargada como unpacked en Chrome (ver más abajo)

Instalación

Vía npx, sin instalación previa:

npx @frankorozcogt/mcp-chrome-server

Para desarrollo local del propio paquete:

npm install
npm run build

Uso

Modo stdio (por defecto, usado por Claude Code u otros clientes MCP):

npx @frankorozcogt/mcp-chrome-server

Con conexión al wrapper Socket.IO habilitada (para el frontend existente):

npx @frankorozcogt/mcp-chrome-server --wrapper-port 8080 --source <sourceId> --project-path /ruta/al/proyecto

En desarrollo, dentro del repo, las variantes equivalentes son node dist/index.js (tras npm run build) o npm run dev (tsx watch).

Configuración de cliente (.mcp.json)

Ver examples/.mcp.json para un ejemplo de configuración de cliente MCP que invoca el server vía npx:

{
  "mcpServers": {
    "chrome": {
      "command": "npx",
      "args": ["@frankorozcogt/mcp-chrome-server", "--wrapper-port", "8080", "--source", "claude"]
    }
  }
}

Opciones:

• --wrapper-port <port>: puerto Socket.IO del wrapper. Si se omite, corre solo en modo stdio.
• --source <sourceId>: identificador de origen para el welcome handshake y los hooks de integración (opcional).
• --project-path <path>: ruta del proyecto, usada para resolver .fcoder/config.json y obtener el projectId (opcional).

Variables de entorno

• LOG_LEVEL: nivel de log de pino (default info). Los logs siempre van a stderr, nunca a stdout.
• MCP_AUTH_TOKEN: reservado para un futuro chequeo de auth. Hoy no hay ningún canal del protocolo (stdio ni Socket.IO) que transporte un token por request, así que configurarlo no bloquea ninguna llamada — es solo un flag de presencia sin efecto real todavía.
• MCP_BACKEND_URL: URL del backend opcional para sync/status. Sin configurar, esos hooks son no-op.
• MCP_AUTO_REGISTER_NATIVE_HOST: controla el auto-registro del native messaging host al arrancar (ver sección siguiente). Default true (activo); poner en false para desactivarlo.

Desarrollo

npm run dev        # tsx watch
npm run typecheck   # tsc --noEmit
npm test            # vitest

Cargar la extensión Chrome

1. Ir a chrome://extensions/.
2. Activar "Modo de desarrollador".
3. "Cargar descomprimida" y seleccionar la carpeta extension/.

La extensión solo puede cargarse como unpacked — usa el permiso debugger, que no es apto para publicación en Chrome Web Store.

Estado actual: las tools de dominio (screenshot, console, network, elements, interact, tabs) y la tool de diagnóstico setup están implementadas y se comunican con la Chrome Extension a través de un native messaging host (mcp-chrome-native-host) y un socket Unix de bridge (--bridge-socket, default /tmp/mcp-chrome-bridge.sock).

Registro automático del native messaging host

Al arrancar, el server verifica que el manifest del native host (com.mcp.chrome) exista y apunte a un ejecutable válido. Si falta o quedó roto (paquete movido/reinstalado, dist/ con otra ruta), lo regenera automáticamente:

• Escribe un wrapper estable en ~/.mcp-chrome-server/chrome-native-host que ejecuta el host.js real del paquete instalado.
• Escribe el manifest de Chrome (NativeMessagingHosts/com.mcp.chrome.json) apuntando siempre a ese wrapper, nunca directo a dist/.

Con esto, cargar la extensión en Chrome (ver más abajo) es el único paso manual — no hace falta correr npm run register-native-host a mano salvo para debugging.

Este comportamiento se controla con MCP_AUTO_REGISTER_NATIVE_HOST (default activo).

Si una tool falla porque no hay ninguna instancia de Chrome conectada al bridge, el server reintenta re-provisionar el native host una vez antes de devolver el error; si sigue sin clientes, el mensaje indica revisar chrome://extensions y reiniciar Chrome. También se puede invocar la tool setup en cualquier momento para diagnosticar/re-provisionar manualmente y ver el estado de la conexión (bridgeClients, extensionConnected, manifestPath, wrapperPath).

Pre-commit hook

El repo incluye .githooks/pre-commit, que corre tsc --noEmit en modo estricto y bloquea commits con errores/warnings de TypeScript o con string primitivo donde debería usarse ProjectId/SourceId.

Para activarlo:

git config core.hooksPath .githooks
chmod +x .githooks/pre-commit

License

MIT — ver LICENSE.