chrome-debug-mcp

chrome-debug-mcp es un servidor asíncrono de Model Context Protocol (MCP) basado en Rust que permite a los agentes de IA y a los grandes modelos de lenguaje controlar, automatizar y depurar de forma nativa navegadores basados en Chromium a través del Chrome DevTools Protocol (CDP).

Al usar cdp-browser-lite por debajo (que a su vez reexporta el cliente cdp-lite), este servidor MCP se conecta directamente con el navegador evitando abstracciones pesadas, lo que permite sesiones de depuración en vivo directamente desde tu editor o interfaz de chat. A partir de la v0.2.0, también puede gestionar automáticamente el ciclo de vida del proceso de Chrome.

✨ Características

Este servidor implementa de forma nativa un conjunto de herramientas categorizadas por dominios CDP y gestión nativa de procesos:

🛡️ Privacidad y seguridad

• Perfiles aislados (predeterminado): Cada vez que el servidor MCP lanza Chrome, crea un perfil de usuario nuevo y temporal en el directorio temporal de tu sistema. Este perfil es completamente independiente del perfil principal de tu navegador y se elimina cuando el navegador se detiene — las cookies, el historial, las contraseñas guardadas o los datos de sesión de una sesión nunca se filtran a la siguiente.

• Experiencia similar al modo incógnito: De forma predeterminada, no se comparten cookies, historial, contraseñas guardadas ni datos de sesión de tus cuentas personales con la instancia gestionada.

• Protección de identidad: Incluso si un LLM tiene control total sobre el navegador, no puede acceder a tus sesiones iniciadas (p. ej., Google, GitHub, banca) ni suplantarte sin autorización explícita.

• Modo de perfil de usuario: Usa la opción --user-profile para lanzar Chrome con tu perfil de sistema existente. Esto es útil cuando quieres que el LLM trabaje dentro de tus sesiones activas (cookies, inicios de sesión guardados, etc.) sin tener que volver a autenticarse en cada sitio. Úsalo con precaución, ya que esto le da al LLM acceso a tus datos personales del navegador.

  • ⚠️ Nota sobre --user-profile: Debido a la arquitectura de instancia única de Chrome, si tu navegador ya está abierto, delegará la solicitud y no podrá abrir el puerto de depuración. Debes cerrar todas las instancias existentes de Chrome antes de iniciar el MCP, o iniciar tu navegador manualmente con la opción --remote-debugging-port=9222.

🚀 Gestión de instancias y pestañas de Chrome

• Soporte multi-instancia: Lanza y controla múltiples procesos de Chrome concurrentes e independientes en puertos dinámicos, cada uno con su propio directorio de perfil aislado. Limita el número de instancias usando la opción --max-instances.

• Herramientas de registro de instancias: Usa open_instance, list_instances y close_instance para crear, auditar y limpiar instancias adicionales. Todas las herramientas existentes aceptan un instance_id opcional para enrutar comandos al navegador objetivo.

• Soporte multi-pestaña (nuevo): Controla múltiples pestañas concurrentes dentro de una única instancia de Chrome, multiplexando los flujos de eventos y comandos a través de una única conexión WebSocket.

  • Detección automática: Las ventanas emergentes abiertas por las páginas objetivo (p. ej., window.open()) se detectan, se adjuntan y se registran automáticamente en el registro de pestañas de la sesión.

  • Aislamiento de caché: Las cachés de estado (mensajes de consola, tráfico de red, scripts analizados por el depurador, herramientas WebMCP) están estrictamente aisladas por pestaña para que los eventos no se filtren entre objetivos.

• Herramientas de registro de pestañas (nuevas):

  • open_tab — Abre una nueva pestaña, opcionalmente con una etiqueta personalizada y una URL de destino. Devuelve JSON con el tab_id para reutilizarlo en otras herramientas.

  • list_tabs — Enumera todas las pestañas abiertas y registradas de la instancia como JSON (tab_id, label, target_id, url) junto con la pestaña activa actual. Cuando no hay pestañas registradas, las herramientas recurren a la conexión predeterminada de pestaña única de la instancia.

  • close_tab — Cierra una pestaña específica por ID y limpia su estado de caché. Devuelve la nueva pestaña activa.

  • switch_tab — Cambia la pestaña activa predeterminada que se usa cuando se omite tab_id en las llamadas a herramientas y, opcionalmente, la trae al primer plano.

• Interfaz amigable para LLM: Las herramientas de ciclo de vida (open_instance, close_instance, open_tab, list_tabs, switch_tab, close_tab) devuelven JSON estructurado para que los agentes puedan encadenar llamadas sin tener que analizar texto con expresiones regulares, y sus descripciones siguen la plantilla estándar de MCP (efectos secundarios, requisitos previos, valores de retorno, alternativas) para que los modelos las clasifiquen correctamente.

• Enrutamiento de objetivos (nuevo): Todas las herramientas de ámbito de pestaña aceptan un parámetro opcional tab_id para dirigir comandos y recuperar el estado de caché de una pestaña específica. Si se omite, se usa la pestaña activa predeterminada.

• Perfiles aislados: Lanza Chrome usando un perfil temporal y nuevo de forma predeterminada, asegurando que no comparta cookies, contraseñas ni datos de sesión con tu navegador principal.

• Soporte de perfil de usuario: Usa opcionalmente --user-profile para aprovechar tus sesiones y cookies existentes del navegador.

• Gestión dinámica de puertos: Detecta automáticamente si el puerto predeterminado (9222) está en uso.

  • Si el puerto está ocupado por una instancia de Chrome que expone CDP (iniciada por el usuario u otra instancia gestionada de chrome-debug-mcp), se adjunta automáticamente a ella en lugar de crear una nueva.

  • Los perfiles gestionados son efímeros, por lo que no hay estado persistente por puerto; un segundo servidor que comparte un puerto simplemente comparte el mismo navegador (y nunca termina una instancia adjuntada).

• Soporte para Docker y modo headless: Compatibilidad total con entornos Docker. Usa la opción --headless para ejecutar Chrome sin interfaz gráfica dentro de contenedores.

• Conexión remota/anfitrión: Usa el argumento --host para conectarte a una instancia de Chrome que se ejecuta en otra máquina o en la máquina anfitriona (p. ej., --host host.docker.internal desde dentro de un contenedor).

• Barra de información de automatización opcional: Añade la opción --enable-automation para mostrar explícitamente el mensaje nativo «Chrome está siendo controlado por software de pruebas automatizado». De forma predeterminada, esto está deshabilitado para una interacción más discreta.

• Soporte de proxy: restart_chrome ahora acepta un argumento opcional proxy_server para lanzar Chrome enrutando el tráfico a través de un proxy.

• Inicio automático: Detecta automáticamente si Chrome se está ejecutando en el puerto especificado. Si no es así, lanza una nueva instancia con las opciones necesarias.

• restart_chrome: Reinicia la instancia gestionada de Chrome.

• Ajustes predefinidos de capacidades: restart_chrome acepta un array opcional features para que un cliente pueda optar por capacidades adicionales del navegador en cada reinicio. Es un conjunto cerrado — las opciones arbitrarias de Chrome no se aceptan deliberadamente, para evitar que la herramienta se convierta en un punto de inyección de línea de comandos:

  • WEB_MCP — habilita la superficie experimental WebMCP (--enable-features=WebMCPTesting, --categoryExperimentalWebmcp=true), para sitios que exponen herramientas al navegador.

  • WEBGL_SOFTWARE — fuerza WebGL por software con SwiftShader (--use-gl=angle, --use-angle=swiftshader, --enable-unsafe-swiftshader), para entornos sin GPU, como contenedores.

  Los ajustes predefinidos se aplican a la instancia iniciada por esa llamada; un restart_chrome posterior que omita features los elimina, reflejando el comportamiento de proxy_server.

• stop_chrome: Apaga la instancia gestionada de Chrome de forma ordenada (SIGTERM/SIGINT con respaldo a SIGKILL).

• Ciclo de vida robusto: Se corrigieron problemas con procesos de Chrome colgados. Los perfiles efímeros se eliminan al detenerse, y cdp-browser-lite limpia los directorios de perfil huérfanos que quedan tras terminaciones abruptas; la burbuja de restauración «Chrome no se cerró correctamente» se suprime mediante opciones de lanzamiento y parcheo del perfil.

• ⚠️ Cambio de comportamiento: Las instancias gestionadas de Chrome ahora se terminan cuando el proceso del servidor MCP sale (incluidos los fallos). Anteriormente, un Chrome gestionado sobrevivía a un fallo del servidor y se volvía a adjuntar al reiniciar; a partir de ahora se termina. Las instancias de Chrome adjuntadas (iniciadas por el usuario) nunca se terminan.

🔐 Autenticación de proxy

• enable_proxy_auth: Gestiona automáticamente los desafíos de autenticación de proxy conectándose al dominio Fetch de CDP y proporcionando las credenciales suministradas por el usuario (nombre de usuario y contraseña).

• Mejoras de robustez: Ahora incluye un tiempo de espera de 30 segundos para proxies residenciales más lentos y, de forma predeterminada, solo intercepta solicitudes Document para evitar romper las solicitudes en segundo plano.

• Pre-calentamiento: Navega automáticamente a un prewarm_url (por defecto, http://api.ipify.org?format=json) para establecer el túnel de proxy de forma fiable antes de tu tarea principal de navegación. Opcionalmente, puedes restringir la interceptación a un resource_type específico.

🖱️ Entrada de usuario

• click_element: Simula un clic de ratón nativo en un elemento específico mediante un selector CSS. Calcula las coordenadas del centro del elemento y envía eventos de ratón de CDP directamente.

• fill_input: Rellena un campo de entrada del DOM con el texto especificado. Enfoca el elemento mediante un selector CSS y luego usa el Input.insertText nativo de CDP.

• scroll: Desplaza la página por píxeles, alturas de viewport (páginas) o hasta un elemento específico. Esencial para interactuar con contenido de carga diferida o scroll infinito.

📡 Inspección de red

• get_network_logs: Recupera las solicitudes de red interceptadas (REST/HTTP) y las tramas WebSocket.

• Filtrado avanzado: Filtra los registros por URL, tipo de recurso, dirección WebSocket o contenido del payload.

• Inspección de payload: Accede a las cabeceras completas de solicitud/respuesta, a los cuerpos de respuesta REST y a las tramas WebSocket.

• Optimizado para contexto: Modo «resumen» opcional para evitar inundar la ventana de contexto del LLM.

🪵 Consola y errores

• get_console_logs: Recupera los registros de consola del navegador. Esto incluye llamadas console.log/warn/error, excepciones y errores de red. Es crucial para solucionar problemas de scripts y errores de la página. Incluye filtrado opcional por nivel de registro y una opción clear para gestionar el estado de manera eficiente.

⚡ Rendimiento y perfilado

• get_performance_metrics: Recupera métricas de rendimiento en tiempo de ejecución del navegador (p. ej., tamaño del montículo de JS, nodos DOM, duración del layout). Útil para obtener una instantánea rápida de la memoria y la sobrecarga computacional de la página.

• profile_page_performance: Graba y analiza un trace de rendimiento de la página. Calcula automáticamente las Core Web Vitals (FCP, LCP, DCL, Load) e identifica las principales Long Tasks (operaciones que bloquean el hilo principal). Opcionalmente, puedes recargar la página con la caché deshabilitada para simular un arranque en frío.

🌐 Control de página y tiempo de ejecución

• capture_screenshot: Toma una captura de pantalla de la página actual (o del diseño de página completo) y la devuelve al cliente LLM como un bloque de imagen codificado en base64.

• navigate: Navega la pestaña activa a una URL específica.

• reload: Recarga la página actual.

• inspect_dom: Obtiene el HTML completo o un fragmento inteligente alrededor de una consulta de búsqueda.

  • Búsqueda contextual: Busca texto específico y obtén un número configurable de caracteres a su alrededor.

  • Eficiencia de tokens: Reduce drásticamente el uso de la ventana de contexto en páginas grandes.

• evaluate_js: Ejecuta una expresión arbitraria de JavaScript globalmente en el contexto de la página.

🐞 Depuración en vivo y control de ejecución

• pause_on_load: Activa el depurador y provoca una recarga de la página, pausando la ejecución en la primera sentencia de script analizada.

• search_scripts: Busca una consulta en todos los contextos de script analizados para localizar con precisión líneas y columnas para puntos de interrupción.

• set_breakpoint: Establece un punto de interrupción JS preciso usando script_id, url o el script_hash exacto.

• evaluate_on_call_frame: Evalúa una expresión de JavaScript directamente dentro del ámbito local del marco de llamada del depurador actualmente pausado.

• step_over: Pasa por encima de la siguiente línea de expresión.

• resume: Reanuda la ejecución.

• remove_breakpoint: Elimina un punto de interrupción establecido previamente.

🧩 WebMCP (herramientas expuestas por la página) Requiere reiniciar Chrome con el preset de capacidades WEB_MCP (consulta restart_chrome).

• webmcp_list_tools: Enumera las herramientas que la página actual expone al navegador (nombre, descripción, inputSchema, frameId).

• webmcp_invoke_tool: Invoca una herramienta de la página por nombre. input es una cadena de objeto JSON (p. ej. "{}" o "{\"product\":\"knot\"}"), que coincide con el inputSchema de la herramienta. Bloquea hasta 30 segundos esperando el resultado.

• webmcp_get_invocation: Devuelve el estado (Pending/Completed/Error/Canceled) y el resultado de una invocación por invocationId — sin bloqueo.

• webmcp_list_invocations: Enumera todas las invocaciones de la sesión con su estado, con filtro opcional por status.

  ⚠️ Diálogos de consentimiento: las herramientas de la página con efectos secundarios (escrituras en el portapapeles, envíos de formularios…) pueden mostrar un diálogo de confirmación en la página que un humano debe hacer clic. En ese caso, webmcp_invoke_tool devuelve un error de tiempo de espera que contiene el invocationId — la invocación permanece en Pending (NO se cancela), por lo que puedes consultarla con webmcp_get_invocation después de que el usuario la apruebe o la deniegue.

🧪 Estabilidad y fiabilidad

• Pruebas unitarias exhaustivas: Suite de pruebas completa que garantiza la fiabilidad del procesamiento de eventos y la deserialización de herramientas, especialmente en el dominio debugger.

• Pruebas sin efectos secundarios: Todas las pruebas unitarias están diseñadas para ejecutarse de forma aislada, sin lanzar instancias reales de Chrome ni modificar el sistema de archivos.

• Refactorización interna: Lógica central desacoplada mediante traits e inyección de dependencias para garantizar la mantenibilidad a largo plazo.

Related MCP server: chrome-devtools-mcp

⚙️ Configuración

Por defecto, el servidor MCP descubre el ejecutable de Chrome mediante la búsqueda multiplataforma de cdp-browser-lite: primero CHROME_PATH (prioridad absoluta), luego los binarios comunes en tu PATH (google-chrome, google-chrome-stable, chromium, chromium-browser), y después las ubicaciones específicas del sistema operativo (/Applications/Google Chrome.app/... en macOS, el directorio de instalación de chrome.exe en Windows, /usr/bin/google-chrome, /opt/google/chrome/chrome y /snap/bin/chromium en Linux). Esto es un superconjunto estricto de las rutas que el servidor tenía codificadas anteriormente.

Argumentos:

• --local: Restringe la navegación solo a direcciones locales (localhost, 127.0.0.1, 192.168.x.x o *.local). Muy recomendado por seguridad.

• --headless: Ejecuta Chrome en modo headless (sin interfaz gráfica). Esencial para entornos Docker o de servidor.

• --user-profile: Usa el perfil de usuario predeterminado del sistema (sesiones, cookies, etc.) en lugar de uno nuevo. Esto es útil para evitar inicios de sesión repetidos durante sesiones de investigación.

• --host: Especifica el host de destino para la instancia de Chrome (por defecto: 127.0.0.1). Usa host.docker.internal para conectarte a una máquina host desde un contenedor.

• --port: Especifica el puerto de depuración remota (por defecto: 9222).

• --enable-automation: Activa la barra de información "controlado por software automatizado".

• --max-instances: Limita el número máximo de instancias de Chrome concurrentes (por defecto: 8). Se ignora si --user-profile está establecido.

Variables de entorno:

• CHROME_PATH: Define explícitamente la ruta al ejecutable de Chrome.

🐳 Uso con Docker y modo headless (v1.0.0)

chrome-debug-mcp está totalmente preparado para contenedores. Esto permite varios casos de uso potentes para LLMs:

1. Despliegue en la nube (mediante Glama)

La forma más sencilla de usar este servidor. Glama crea un contenedor Docker con Chrome preinstalado. El LLM obtiene acceso inmediato a un navegador en la nube sin ninguna configuración local.

2. Uso local aislado

Ejecuta todo dentro de Docker para evitar instalar Chrome o Rust en tu máquina host:

docker build -t chrome-mcp .
docker run -i --rm chrome-mcp --headless

3. Modo híbrido (el contenedor controla el host)

El servidor MCP se ejecuta dentro de un contenedor Docker seguro, pero controla la instancia de Chrome en tu escritorio real. Esto permite que el LLM te asista en tu sesión de navegación real:

1. Inicia tu Chrome local con: --remote-debugging-port=9222

   • Nota: Si necesitas soporte de proxy en este modo, también debes iniciar Chrome con el flag --proxy-server="http://your-proxy:port".

2. Ejecuta el contenedor:

# On macOS/Windows
docker run -i --rm chrome-mcp --host host.docker.internal

🚀 Inicio rápido

La forma más sencilla de instalar y ejecutar el servidor MCP de forma nativa es mediante Cargo de Rust o descargando los binarios precompilados. Ya no necesitas iniciar Chrome manualmente; el servidor MCP lanzará automáticamente una instancia visible de Chrome con los flags de depuración correctos.

1. Instalación

Opción A: Binarios precompilados (recomendado) Ve a la página de Releases y descarga el ejecutable nativo para tu plataforma (macOS, Windows, Linux). Proporcionamos instaladores .msi para Windows y scripts de shell para sistemas UNIX.

Opción B: Instalar mediante Cargo

cargo install --git https://github.com/raultov/chrome-debug-mcp

Opción C: Instalar mediante script de shell (Unix)

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/raultov/chrome-debug-mcp/releases/latest/download/chrome-debug-mcp-installer.sh | sh

2. Configura tu cliente MCP

Este servidor está completamente probado y confirmado para funcionar con Claude Code, agy y codex. Configura tu cliente de IA para ejecutar el servidor usando cualquiera de los siguientes modos.

Configuración universal (JSON)

La mayoría de los clientes MCP (como Claude Code o cualquier configuración basada en JSON) usan esta estructura. Estos son los tres modos de uso principales:

{
  "mcpServers": {
    "chrome-debug-mcp": {
      "command": "chrome-debug-mcp",
      "args": [],
      "env": {}
    },
    "chrome-docker": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "chrome-debug-mcp:v1.0.9", "--headless"]
    },
    "chrome-docker-hybrid": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--net=host",
        "chrome-debug-mcp:v1.0.9",
        "--host",
        "127.0.0.1"
      ]
    }
  }
}

Nota: El modo chrome-docker-hybrid usando --net=host es la forma recomendada en Linux para permitir que el contenedor acceda a tu instancia local de Chrome en 127.0.0.1.

Claude Code

Para añadir y activar el servidor en Claude Code:

claude mcp add chrome-debug-mcp chrome-debug-mcp

3. Uso

Una vez conectado, el agente de IA se encargará automáticamente de iniciar Chrome cuando se ejecute el primer comando. El navegador permanecerá visible para que puedas seguir visualmente el proceso de depuración.

4. Flujos de trabajo del agente y guía de múltiples instancias

Los LLMs pueden operar este servidor usando algunos patrones optimizados:

A. Escenarios aislados de múltiples instancias

Al ejecutar sesiones de navegador automatizadas, puedes lanzar procesos de Chrome separados para evitar la contaminación de cookies o la colisión de pestañas:

1. Llama a open_instance con label: "user-session-1" o configuraciones opcionales de servidor proxy. Esto devuelve un instance_id único (p. ej. chrome-2).

2. Pasa el instance_id explícitamente a herramientas posteriores como navigate, evaluate_js o webmcp_list_tools.

3. Libera recursos usando close_instance una vez terminado.

B. Trabajar con WebMCP

Si navegas a una página que admite WebMCP (p. ej., https://www.knot.kz/#/agent-tools):

1. Las herramientas registradas por la página web se pueden recuperar usando webmcp_list_tools.

2. Por defecto, WEB_MCP está deshabilitado por seguridad. Si la lista de herramientas está vacía, llama a restart_chrome con features: ["WEB_MCP"] y luego a reload.

3. Invoca las herramientas de la página usando webmcp_invoke_tool, proporcionando argumentos JSON de entrada. Si un diálogo de consentimiento pausa la ejecución en la página web, la herramienta agotará el tiempo de espera después de 30 segundos pero mantendrá la invocación pendiente. Puedes consultar su resultado usando webmcp_get_invocation.

🛠 Compilación (desde el código fuente)

Si deseas compilar desde el código fuente:

git clone https://github.com/raultov/chrome-debug-mcp
cd chrome-debug-mcp
cargo build --release

El binario resultante se ubicará en target/release/chrome-debug-mcp. Este proyecto utiliza cargo-dist para gestionar la distribución nativa multiplataforma sin problemas mediante GitHub Actions.

📖 ¿Por qué este servidor MCP?

Otros servidores de integración como los wrappers de Puppeteer/Playwright son de alto nivel, pesados y normalmente fallan a la hora de exponer depuradores reales e interactivos paso a paso. Este servidor MCP usa mensajes CDP sin procesar, mapeándolos 1:1 a herramientas de LLM, lo que permite a los agentes inteligentes literalmente pasar por encima de JS, leer variables del ámbito local de forma nativa, buscar dentro de los contextos del compilador V8 y entender exactamente por qué un script está fallando.

📜 Licencia

Este proyecto está licenciado bajo la Licencia MIT. Consulta el archivo LICENSE para más detalles.