chrome-devtools-mcp-mux

Comparte una instancia de Chrome entre muchos clientes MCP. Cada cliente —una sesión separada de Claude Code, por ejemplo— obtiene su propio conjunto aislado de pestañas, mientras todos se ejecutan contra el mismo navegador y perfil.

Qué problema resuelve

chrome-devtools-mcp expone Chrome DevTools a un cliente MCP. Funciona perfectamente para un cliente, pero si dos clientes se conectan a la vez (dos ventanas de Claude Code, un Claude Code más un CLI de Gemini, etc.) interfieren con las pestañas del otro — list_pages muestra todo, select_page compite, new_page aterriza en la ventana incorrecta.

cdmcp-mux se sitúa entre los clientes y chrome-devtools-mcp y otorga a cada conexión su propio conjunto de pestañas aislado, mientras mantiene un único Chrome en ejecución.

Instalar y configurar (una sola vez)

git clone <this-repo> chrome-devtools-mcp-mux
cd chrome-devtools-mcp-mux
npm install
npm run build
npm link           # exposes `cdmcp-mux` on PATH

Luego, en el archivo .mcp.json de cada cliente MCP:

{
  "mcpServers": {
    "chrome": { "command": "cdmcp-mux" }
  }
}

Eso es todo. El primer cliente en conectarse genera automáticamente un demonio compartido; los clientes posteriores se conectan al mismo demonio.

Cómo verificar que funciona

Inicia dos clientes MCP con la configuración anterior. En cada uno, pídele al modelo que:

1. Abra una URL diferente mediante new_page.

2. Ejecute list_pages.

Cada cliente debería ver solo su propia página. En el host, ejecuta cdmcp-mux status para ver ambos contextos lado a lado en el demonio.

Para una demostración completa con guion y un video grabado, consulta demo/.

Variables de entorno (opcional)

Depuración

Todo fuera de banda; el mux nunca expone herramientas de depuración a los clientes MCP.

El registro se encuentra en ~/.local/state/cdmcp-mux/mux.log.

Cómo funciona

flowchart TB
    subgraph clients["one process per MCP client"]
      direction LR
      C1["Claude Code #1"] -- "stdio (MCP)" --> S1["cdmcp-mux shim"]
      C2["Claude Code #2"] -- "stdio (MCP)" --> S2["cdmcp-mux shim"]
    end

    subgraph shared["shared — auto-spawned on first connect"]
      direction TB
      D["mux daemon<br/><i>per-connection context table</i><br/>(socket fd → ctxId → owned pageIds)"]
      U["chrome-devtools-mcp subprocess<br/><code>--experimentalPageIdRouting</code><br/><code>--userDataDir <fixed></code>"]
      B["Chromium<br/><i>one instance, one profile</i>"]
      D -- "stdio (MCP)<br/>rewrite + filter" --> U
      U -- "CDP" --> B
    end

    S1 -- "unix socket" --> D
    S2 -- "unix socket" --> D

    classDef client fill:#e3f2fd,stroke:#1976d2
    classDef shim fill:#fff3e0,stroke:#f57c00
    classDef core fill:#f3e5f5,stroke:#7b1fa2
    classDef browser fill:#e8f5e9,stroke:#388e3c
    class C1,C2 client
    class S1,S2 shim
    class D,U core
    class B browser

Cada cliente MCP genera su propio shim cdmcp-mux (así es como funciona .mcp.json — un hijo por cliente). El shim es un conducto de bytes puro entre el stdio del cliente y un socket unix; el primer shim en conectarse genera automáticamente el demonio compartido, los shims posteriores se conectan a él. El demonio posee un subproceso chrome-devtools-mcp que controla un Chromium con un --userDataDir.

Cada conexión de socket unix = un nuevo BrowserContext (cookies aisladas, localStorage, WebSockets). El demonio anuncia exactamente los mismos esquemas de herramientas que el chrome-devtools-mcp estándar — pageId y isolatedContext se eliminan de lo que ve el cliente, y se reinyectan en cada tools/call desde la tabla de propiedad por conexión del demonio. La atomicidad utiliza --experimentalPageIdRouting del upstream, por lo que las llamadas simultáneas desde diferentes contextos no pueden sobrescribirse entre sí. Cuando un cliente se desconecta, sus pestañas se cierran y su contexto de navegador se destruye.

Notas de desarrollo

Este proyecto fue escrito de principio a fin por un agente de Claude-Code en una sola sesión de trabajo, impulsado por requisitos conversacionales en vivo. El plan de pruebas completo está escalonado para la corrección funcional (58 pruebas, ~19 s, todas aprobadas), y el multiplexor fue luego demostrado visualmente a través de un reproductor automatizado por VNC.

Para el mapeo de PRD a prueba, consulta DEMO.md. Para el registro completo de desarrollo agéntico — descubrimiento de requisitos, iteración de arquitectura, escalonamiento de pruebas y las tres tomas de la demostración en video — consulta demo/README.md.

Pruebas

# requires a Chromium binary; the smoke/e2e tests need it
CDMCP_MUX_CHROMIUM=/usr/bin/chromium npm test

Esperado: 8 archivos, 58 pruebas, todas aprobadas.

Lanzamiento

La CI se ejecuta en cada push y PR contra main usando Node 22 y 24, compilando, verificando tipos y ejecutando el conjunto completo de 58 pruebas (incluyendo las pruebas de humo de Chromium real y las pruebas binarias e2e).

La publicación está automatizada a través de .github/workflows/publish.yml, que se ejecuta al publicar una versión en GitHub:

1. Aumentar la version en package.json, hacer commit, etiquetar como v<version>.

2. gh release create v<version> --generate-notes.

3. El flujo de trabajo compila, prueba y ejecuta npm publish con procedencia de npm (firmado mediante OIDC de GitHub, el flujo de trabajo tiene id-token: write).

NPM_TOKEN es el único secreto de repositorio requerido. El paquete se publica con publishConfig.provenance: true, por lo que la bandera --provenance es implícita. Una vez que este repositorio se registre como editor de confianza en npmjs.com, el secreto NPM_TOKEN puede eliminarse por completo.

Licencia

Apache-2.0 — ver LICENSE. Igual que el chrome-devtools-mcp original.