Custom Chrome Dev MCP

Un servidor MCP (Model Context Protocol) solo local que permite que un cliente MCP - Claude Code, o cualquier otra cosa que hable MCP - controle tu Chrome real de la misma manera que lo haría una persona. Sin telemetría, sin servicios de terceros, sin nube: todo se ejecuta en tu máquina detrás de un token compartido.

Expone 45 herramientas en navegación, pestañas, percepción, interacción, entrada confiable, observabilidad y captura.

De dónde viene esto

Este proyecto está inspirado en el MCP de navegador oficial de Chrome - el Chrome DevTools MCP servidor publicado por el equipo de Chrome DevTools, que fue el primero en argumentar que un agente de IA debería controlar un navegador a través del Protocolo DevTools en lugar de a través de HTML extraído.

Estamos replicando e imitando esa idea, no distribuyéndola. Lo que tomamos prestado:

• La premisa - exponer el navegador a un agente como un conjunto de herramientas MCP.

• Percepción basada en accesibilidad - entregar al modelo un esquema de accesibilidad compacto con referencias de elementos estables en lugar de un muro de HTML crudo.

• El Protocolo DevTools de Chrome como capa de entrada - eventos reales y confiables en lugar de sintéticos que una página puede detectar e ignorar.

Donde este proyecto se desvía deliberadamente:

Esa última fila es el punto central de este repositorio. Chrome DevTools MCP es una herramienta de depuración que resulta que controla un navegador; esto es una herramienta de imitación-de-una-persona que resulta útil para depurar.

⚠️ No está afiliado, respaldado ni soportado por Google o el equipo de Chrome. Esta es una reimplementación independiente creada para aprender de su diseño e imitarlo. Usa el servidor oficial si quieres la versión soportada.

Related MCP server: monkeysee

Mantiene deliberadamente el estilo de un humano

La mayoría de la automatización de navegadores es trivialmente detectable: eventos sintéticos con isTrusted=false, foco que nunca se mueve realmente, texto que aparece en un campo de una sola vez, un perfil de automatización impecable sin historial. Cada uno de esos es una señal.

Este proyecto intenta eliminar esas señales:

• Tu perfil real. Las acciones se ejecutan en el Chrome que ya usas: tus cookies, inicios de sesión, extensiones e historial. Nada que marcar como "automatización nueva".

• Entrada confiable. realClick, realType, press, hover y drag se envían a través del Protocolo DevTools, por lo que la página recibe eventos con isTrusted=true - el mismo indicador que produce un mouse y teclado físicos.

• Foco genuino. Hacer clic para enfocar un campo realmente mueve el foco, en orden, en lugar de asignar .value a espaldas de la página.

• Pulsaciones de teclas reales. press emite secuencias adecuadas de rawKeyDown / char / keyUp con códigos de tecla y modificadores correctos, no un único evento sintético de input.

• Verificación de lectura. fill confirma que el campo realmente contiene el texto, para que el agente note cuando una página rechazó silenciosamente la entrada, como lo haría una persona.

El objetivo: una página debe comportarse para el agente exactamente como se comporta para alguien sentado frente al teclado.

Las herramientas sintéticas rápidas (click, type) siguen ahí: son más rápidas y funcionan en la mayoría de los sitios. Cuando una página las ignora, recurre a las equivalentes confiables.

Cómo funciona

Un transporte. El cliente MCP habla con el servidor a través de stdio; el servidor retransmite a una extensión de Chrome a través de un WebSocket local propiedad de un proceso hub pequeño y de larga duración.

MCP client 1 (Claude) <-stdio-> bin/custom-chrome-dev-mcp.js ─┐
MCP client 2 (Claude) <-stdio-> bin/custom-chrome-dev-mcp.js ─┼─ src/hub.js (127.0.0.1:9876)
MCP client N (Claude) <-stdio-> bin/custom-chrome-dev-mcp.js ─┘              │
                                                                            │ WebSocket
                                                                            ▼
                                                              Chrome extension -> active tab

Por qué un proceso hub separado. Solo un proceso puede ser dueño del puerto 9876, pero puedes tener varias sesiones de Claude abiertas y todas pueden querer el navegador. Así que el socket vive en src/hub.js en lugar de dentro de cualquier sesión. Cada sesión se conecta al hub como role:"mcp", la extensión se conecta como role:"extension", y el hub multiplexa entre ellos. La primera sesión que se inicia genera el hub de forma separada, por lo que sobrevive a esa sesión; las sesiones posteriores lo encuentran ya escuchando.

Dentro de la extensión hay tres capas:

1. Walker (page/walker.js) - se inyecta en el mundo AISLADO de la página. Es dueño de la resolución de elementos, el mapa de referencias estables eN, y las operaciones sintéticas rápidas del DOM.

2. CDP (cdp/) - chrome.debugger para entrada confiable, evaluate en el contexto de la página, capturas de pantalla de página completa, y los buffers de consola/red.

3. Grabación (recording/) - fotogramas de screencast de CDP codificados a .webm por un MediaRecorder en un documento fuera de pantalla.

🔒 La extensión se autentica con el hub mediante un token compartido (AUTH_TOKEN, idéntico en src/config.js y extension/src/config.js). El hub descarta cualquier par que presente un valor diferente.

Requisitos previos

Sin instalaciones globales, sin paso de compilación, sin servicio al que registrarse. Dos dependencias de ejecución (@modelcontextprotocol/sdk y ws) y todo permanece en 127.0.0.1.

Configuración local

Cuatro pasos, luego una verificación. Presupuesta cinco minutos.

1. Clonar e instalar

git clone <your-fork-url> custom-chrome-dev-mcp
cd custom-chrome-dev-mcp
npm install

Confirma que el árbol está sano antes de conectar cualquier cosa a Chrome: la vía sin conexión no necesita navegador y tarda menos de un segundo:

npm test

Quieres 22 passed. Si falla, arréglalo antes de continuar; nada más adelante funcionará.

2. Cargar la extensión en Chrome

1. Abre chrome://extensions.

2. Activa Modo de desarrollador (interruptor en la parte superior derecha).

3. Haz clic en Cargar descomprimida y selecciona la carpeta extension/ - la carpeta en sí, no manifest.json dentro de ella.

4. Custom-chrome-dev-mcp aparece en la lista.

⚠️ Cárgala en el perfil de Chrome en el que realmente navegas. Chrome mantiene extensiones por perfil, por lo que una extensión cargada en "Perfil 4" es invisible para la ventana que se ejecuta bajo "Default". Si las herramientas luego informan que no hay pestañas, o el hub nunca registra extension connected, esto es lo primero que debes verificar. chrome://version muestra la Ruta del perfil activa.

El ID de la extensión está fijado por la key pública en extension/manifest.json, por lo que es idéntico en todas las máquinas: no hay nada que copiar entre configuraciones.

3. Registrar el servidor MCP con tu cliente

Usa la CLI - sustituye la ruta absoluta donde clonaste el repositorio (pwd en la raíz del proyecto la imprime):

claude mcp add -s user custom-chrome-dev-mcp -- node /ABSOLUTE/PATH/TO/custom-chrome-dev-mcp/bin/custom-chrome-dev-mcp.js

• -s user lo registra para todos tus proyectos; -s local lo limita a este.

• Registra bin/custom-chrome-dev-mcp.js - ese archivo es el punto de entrada. Apuntar a src/server.js no funcionará.

• La ruta debe ser absoluta. Una ruta relativa se resuelve contra el directorio desde el que el cliente se lanzó.

• Confirma con claude mcp list - quieres un ✔ Connected junto a él.

⚠️ No edites manualmente ~/.claude.json. Es grande, y una coma mal colocada rompe Claude Code por completo. El comando anterior lo edita de forma segura.

Agrega el servidor bajo mcpServers:

{
  "mcpServers": {
    "custom-chrome-dev-mcp": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/custom-chrome-dev-mcp/bin/custom-chrome-dev-mcp.js"]
    }
  }
}

4. Reiniciar el cliente MCP

Los clientes MCP enumeran las herramientas una vez, al inicio: un servidor registrado a mitad de sesión es invisible hasta que reinicies. Reinicia Claude y aparecerán las 45 herramientas.

Al reiniciar, el cliente lanza el servidor, que genera src/hub.js si nada está ya escuchando en 127.0.0.1:9876.

5. Verificar los tres eslabones de la cadena

La pila es cliente → servidor → hub → extensión → pestaña. Verifícala de extremo a extremo en lugar de adivinar qué eslabón está caído.

# The hub is up, and the extension found it:
tail -f "$TMPDIR/custom-chrome-dev-mcp-hub.log"
#   [hub] listening on 127.0.0.1:9876
#   [hub] extension connected      <- this line is the handshake succeeding

# Who owns the port (should be src/hub.js from THIS repo):
lsof -nP -iTCP:9876 -sTCP:LISTEN

Luego pide a tu cliente listTabs. Un array JSON de tus pestañas abiertas significa que cada eslabón funciona. Continúa con screenshot - un PNG aterriza en ~/Downloads y vuelve en línea.

Para la consola propia de la extensión: chrome://extensions → Custom-chrome-dev-mcp → service worker → Inspect. Ahí es donde aparecen los errores del lado de la extensión; nunca llegan al cliente MCP.

6. Cambiar el token compartido antes del uso real

AUTH_TOKEN viene con un valor predeterminado, definido de manera idéntica en src/config.js y extension/src/config.js. Es lo único que impide que otro proceso en tu máquina controle tu navegador con sesión iniciada. Elige tu propio valor, cámbialo en ambos archivos (una prueba sin conexión verifica que coincidan) y recarga la extensión.

Después de cambiar código

Las dos mitades se recargan de manera diferente, y equivocarse en esto pierde más tiempo que cualquier otra cosa en el proyecto:

Solución de problemas

Configuración

Ambas son variables de entorno opcionales que src/config.js lee al arrancar.

También vale la pena cambiarlo para uso real: AUTH_TOKEN, definido de forma idéntica en src/config.js y extension/src/config.js. Elige tu propio valor: es lo que impide que otro proceso local controle tu navegador.

Herramientas disponibles (45)

Los elementos se apuntan de tres formas: selector (CSS), ref (un id eN estable de snapshotA11y), o name (nombre accesible, p. ej. la etiqueta de un botón). "target" abajo significa cualquiera de esas tres.

Parámetros universales, aceptados por todas las herramientas:

• tabId - actuar sobre una pestaña específica en lugar de la activa del entorno.

• frameId (de listFrames) - actuar dentro de un frame específico, incluidos iframes de origen cruzado que el documento superior no puede scriptear.

• expectUrl - una protección: rechaza la acción a menos que la URL de la pestaña contenga esta subcadena.

Fija una pestaña de trabajo para toda la sesión con useTab para que una pestaña en segundo plano (un vídeo con reproducción automática, un popup de notificación) no pueda robar el foco y desviar una acción.

Navegación

Pestañas y frames

Percepción

Interacción: sintética, rápida

Eventos no confiables despachados por el walker. Rápida y suficiente para la mayoría de los sitios.

Entrada confiable y emulación: CDP

Eventos reales con isTrusted=true. Estos adjuntan chrome.debugger, que muestra un banner amarillo persistente de "being debugged" en la pestaña.

Observabilidad - CDP, con búfer por pestaña

La captura comienza cuando se conecta el depurador, así que recarga la página después de la primera llamada CDP si quieres ver la actividad desde el momento de la carga.

Captura

Se guarda en el directorio de captura (~/Downloads/ por defecto; consulta Configuración).

path es un nombre de archivo o una ruta dentro del directorio de captura. Las subcarpetas que faltan se crean; cualquier cosa que resuelva fuera del directorio queda rechazada.

Una primera ejecución real

El paso 5 de la configuración prueba el conexionado. Aquí está la parte interesante: que una página vea una persona en lugar de un script. Apunta tu cliente a cualquier página y pide:

1. snapshotA11y - el esquema compacto, con referencias eN para apuntar los blancos.

2. realClick {ref:"e3"} - un clic de confianza. En la pestaña aparece un banner amarillo "siendo depurado"; esa es la conexión CDP, y es intencionalmente visible.

3. evaluate {expression:"'ok'"} - JS en el contexto de la página, evitando el CSP del content script.

4. screenshot - un PNG en tu directorio de captura y devuelto en línea.

5. record {action:"start"} … record {action:"stop", path:"clip.webm"} - un .webm de la pestaña. No hace falta clic en la barra de herramientas ni gesto del usuario; el icono de la barra es inerte por diseño y no inicia nada.

6. detach - quita el banner.

Para ver la diferencia que hace la vía de confianza, instala un listener y compara:

// via evaluate
window.__e = []; document.querySelector("button")
  .addEventListener("click", e => window.__e.push(e.isTrusted));

click informa false; realClick informa true. Ese contraste es el sentido del proyecto, y la vía de pruebas de navegador lo comprueba directamente.

Ejecutar los tests

La suite tiene dos vías, y la división es la clave.

Vía sin conexión - sin navegador, se ejecuta en CI

npm test        # node test/run.mjs --lane=offline

Completa en poco menos de un segundo y no necesita más que Node. Ejecuta un handshake MCP real en proceso contra src/server.js (a través del transporte en memoria del SDK), por lo que verifica la superficie que el servidor realmente publica:

• cada herramienta publicada tiene un handler en la extensión, y viceversa - el fallo que la arquitectura espejo invita a cometer

• ningún nombre deherramienta es reclamado por dos grupos de handlers (se fusionan por spread, así que un duplicado se perdería en silencio)

• cada herramienta lleva una descripción real y el ámbito universal tabId/frameId/expectUrl

• cada herramienta está ejercitada por al menos un test - añade una herramienta sin test y CI falla, sin necesidades un navegador

• la allowlist de rutas de captura rechaza de verdad .., los .. en profundidad, rutas absolutas y escapes mediante symlink, probado contra el resolver real

• la lista de exclusión se comprueba por comportamiento: bloquea lo que dice bloquear y no sobrebloquea sitios ordinarios

• el hub enlace solo loopback, los tokens coinciden en ambos lados, el manifest no pide permisos demasiado amplios, el icono de la barra es inerte, y no se incluye ningún *.pem

Vía de navegador - maneja Chrome real

# 1. Disconnect the MCP client (close Claude Code, or disable this server for the run)
# 2. Free port 9876 - the hub is long-lived and outlives the session that spawned it
pkill -f src/hub.js
# 3. Start the suite; it binds 9876 itself and waits for the extension
npm run test:browser
# 4. Reload the extension in chrome://extensions so it connects to the suite

⚠️ El paso 1 no es opcional. Un cliente MCP conectado relanza el hub cada ~1.2s siempre que ve el socket desaparecido, así que recupera el puerto 9876 al momento y la suite muere con EADDRINUSE. Matar el hub mientras hay cliente conectado no ayuda: el cliente simplemente abre otro nuevo.

La suite levanta un servidor fixture y un puente que habla el mismo protocolo de red que el hub de verdad, de modo que una ejecución que acierta ejercita el contrato del mensaje real. Cada suite refleja un grupo de herramientas, y cada test perfecciona el mismo fixture reset - no test recoge las mutaciones de otro.

Al final imprir la cobertura de herramientas y falla si alguna de las 45 herramientas quedó sin probarse.

Opciones

Estructura de los tests

test/
├── run.mjs                    # CLI: lanes, filtering, coverage, reporting
├── lib/
│   ├── runner.js              # suite registry, isolation, timeouts
│   ├── assert.js              # assertions with diagnostic messages
│   ├── wait.js                # eventually() - polling, not fixed sleeps
│   ├── mcp-probe.js           # real in-process MCP handshake
│   ├── bridge.js              # stands in for the hub; tracks tool coverage
│   ├── fixture-server.js      # serves the fixture pages
│   └── page.js                # the browser session + per-test reset
├── fixtures/
│   ├── index.html             # the fixture page (a real file, with __reset())
│   └── frame.html             # child frame, for frameId targeting
└── suites/
    ├── 01-contract.suite.js   # offline
    ├── 02-security.suite.js   # offline
    ├── 10-navigation.suite.js
    ├── 20-tabs.suite.js
    ├── 30-perception.suite.js
    ├── 40-interaction.suite.js
    ├── 50-trusted-input.suite.js
    ├── 60-observability.suite.js
    └── 70-capture.suite.js

Notas de seguridad

Esta extensión puede controlar tu navegador con la sesión iniciada. Lee esta sección.

• Solo loopback. El hub se vincula a 127.0.0.1, por lo que no es alcanzable desde la LAN: solo desde procesos de esta máquina.

• Handshake de token. Cualquier compañero debe mostrar AUTH_TOKEN al conectar o el hub lo descarta. Cámbialo respecto al valor incluidosed (constante idéntica en src/config.js y extension/src/config.js): es lo que evita que otro proceso local maneje tu navegador.

• Escrituras de archivos confinadas al directorio de captura. src/capture/capture-path.js resuelve cada ruta solicitada y rechaza cualquier cosa fuera de él, incluida la travesía con .. y mediante subdirectorios symlink. Esto importa más de lo que parece: escrituras incontroladas en rutas son efectivamente ejecución de código.

• Lista de bloquear BANLIST en extension/src/config.js bloquea la navegación y scripting en sitios delicados (banca, PayPal, Gmail). Adáptala a tus necesidades. Nota: las capturas y grabaciones generan píxeles render mix y no las filtra la lista.

• El banner de depurador es una característica. Las herramientas CDP invocan chrome.debugger, mostrando una barra amarilla persistente "siendo depurado". Esta es tu señal visible de que algo está conduciendo la pestaña. detach lo elimina.

• evaluate ejecuta JS arbitrario en Contexto real de la página.

• Las páginas internas no están disponibles: la extensión no puede ejecutar scripts en URLs chrome:// o chrome-extension://.

• La clave de firma no está en el repo. El ID de la extensión queda fijado por la clave pública key en extension/manifest.json; la privada correspondiente debe estar fuera del control de versiones (.gitignore bloquea *.pem ). Solo vale para reempaquetar un .crx con el mismo ID: cargar "unpacked" no la utiliza.

Arquitectura

El servidor y la extensión son modulares. Cada grupo de herramientas en src/tools/ tiene un archivo de handlers del mismo nombre en extension/src/handlers/. Añadir una herramienta significa tocaragar exactamente ese par: su esquema y docs a un lado, su implementación al otro.

lo demás es infraestructura de apoyo:

• bin/custom-chrome-dev-mcp.js - el ejecutable que registras en tu cliente MCP. No hace nada más que iniciar el servidor.

• src/config.js / extension/src/config.js - todos los parámetros configurables, un archivo por lado. AUTH_TOKEN y el puerto deben coincidir en los dos.

• src/relay/hub-client.js - se conecta al hub con el rol role:"mcp", lo inicia cuando no está presente y convierte cada llamada de herramienta en una solicitud/respuesta a través del socket.

• src/hub.js - el relay de larga vida propietario de ws://127.0.0.1:9876. Mantiene el único socket de la extensión junto con el cliente de cada sesión y multiplexa entre ellos. Re-etiqueta los IDs en la comunicación (pueden colisionar entre sesiones) y se sale por sí mismo si el hub ya posee el puerto.

• src/capture/capture-path.js - la lista blanca de escritura. Cada ruta de captura pasa por él.

• extension/src/connection.js - el socket del hub y el latido. Un service worker de MV3 se termina tras ~30s de inactividad, lo que deja caer silenciosamente el socket; un latido de menos de 30s mantiene ambos con vida, y una alarma revive al worker tras un cierre forzado.

• extension/src/tabs.js - qué pestaña actúa en una llamada (tabId explícito > pestaña fijada > pestaña activa), la protección de expectUrl y la comprobación de la lista negra.

• extension/src/walker-bridge.js + extension/src/page/walker.js - el script inyectado en el mundo ISOLATED con el sistema estable de referencias a elementos, y el único módulo que sabe cómo llegar a él.

• extension/src/cdp/ - session.js (adjuntar/separar, cdp(), centros de elementos), keyboard.js (nombres de teclas → eventos de teclado CDP), dialogs.js (política de diálogos nativos), buffers.js (búferes circulares de consola y red, con un límite de 500 por pestaña).

• extension/src/recording/ - chrome.tabCapture necesita una interacción del usuario que una llamada MCP nunca tiene, así que la grabación usa el screencast de CDP en su lugar: fotogramas JPEG enviados a un MediaRecorder fuera de pantalla (el service worker no tiene DOM).

• test/ - suite de dos carriles: una verificación de CI sin conexión que no necesita navegador, y una vía de navegador que controla Chrome real. Consulta Ejecución de las pruebas.

Estructura del proyecto

.
├── bin/
│   └── custom-chrome-dev-mcp.js   # executable entry - register THIS with your client
├── src/
│   ├── server.js                  # composes config + relay + tool registry
│   ├── config.js                  # port, token, capture dir, timeouts
│   ├── hub.js                     # long-lived relay owning :9876
│   ├── relay/
│   │   └── hub-client.js          # session -> hub socket; call()
│   ├── capture/
│   │   └── capture-path.js        # write allowlist for screenshots/recordings
│   └── tools/                     # ONE FILE PER TOOL GROUP - the public surface
│       ├── index.js               # the registry
│       ├── schemas.js             # shared arg shapes + passthrough helper
│       ├── navigation.js
│       ├── tabs.js
│       ├── perception.js
│       ├── interaction.js
│       ├── trusted-input.js
│       ├── observability.js
│       └── capture.js
├── extension/                     # Chrome MV3 extension
│   ├── manifest.json
│   └── src/
│       ├── background.js          # service worker entry - wiring only
│       ├── config.js              # token, banlist, buffer caps, asset paths
│       ├── connection.js          # hub socket + MV3 keepalive heartbeat
│       ├── tabs.js                # tab resolution, pinning, ban check
│       ├── walker-bridge.js       # channel to the injected page script
│       ├── cdp/
│       │   ├── session.js         # attach/detach, cdp(), element centres
│       │   ├── keyboard.js        # key names -> CDP key events
│       │   ├── dialogs.js         # native alert/confirm/prompt policy
│       │   └── buffers.js         # console + network ring buffers
│       ├── recording/
│       │   ├── recorder.js        # CDP screencast -> offscreen encoder
│       │   ├── offscreen.html
│       │   └── offscreen.js       # MediaRecorder host
│       ├── page/
│       │   └── walker.js          # injected DOM driver (ISOLATED world)
│       └── handlers/              # MIRRORS src/tools/ - one file per group
│           ├── index.js           # the handler table + dispatch
│           ├── navigation.js
│           ├── tabs.js
│           ├── perception.js
│           ├── interaction.js
│           ├── trusted-input.js
│           ├── observability.js
│           └── capture.js
└── test/                          # two lanes: offline (CI) + browser
    ├── run.mjs                    # CLI entry
    ├── lib/                       # runner, assertions, bridge, fixtures, session
    ├── fixtures/                  # the fixture pages, as real files
    └── suites/                    # one suite per tool group

Créditos

Inspirado por Chrome DevTools MCP del equipo de Chrome DevTools. Reimplementación independiente, no afiliada a Google, ni avalada ni respaldada por Google.

Licencia

MIT. Copyright (c) 2026 Haba Andrei.

Úsalo, hazle un fork, publícalo. La única condición es que el aviso de copyright y el aviso de permiso viajen con cualquier copia sustancial.