CubeLabs

1. Por qué un agente necesita controlar el navegador

Un agente de código (Claude Code, Cursor, Copilot…) es excelente leyendo y editando tu código fuente, pero la aplicación que construyes vive en otro sitio: en el navegador. Para arreglar un bug de layout, entender por qué una petición falla o comprobar si la página carga rápido, el agente necesita ver la app corriendo de verdad.

Sin esta pieza, el flujo típico es frustrante: el agente adivina el comportamiento de la página, tú le pegas capturas de pantalla, y el ciclo de feedback es lento y manual. Con Chrome DevTools MCP el agente abre Chrome él mismo, inspecciona el DOM, lee la consola, mira la pestaña Network y ejecuta JavaScript real en la página.

Casos donde marca la diferencia:

• Debugging — "la petición a /api/checkout falla solo en producción": el agente abre la página, mira la pestaña Network y lee el error exacto con su stack trace.
• Automatización de tareas web — rellenar formularios, probar flujos de login, verificar que un botón existe tras un cambio.
• Rendimiento — "mi landing va lenta": el agente graba una traza y te dice qué está bloqueando el LCP.
• Testing visual y funcional — comparar estados, auditar accesibilidad y SEO con Lighthouse.

2. Qué es Chrome DevTools MCP y cómo encaja en MCP

Chrome DevTools for agents (chrome-devtools-mcp) es un proyecto oficial del equipo de Chrome DevTools que deja que tu agente de código controle e inspeccione un Chrome vivo. Actúa como un servidor MCP: el agente (cliente MCP) habla con él en JSON-RPC y él habla con Chrome vía DevTools Protocol, usando Puppeteer para automatizar y esperando automáticamente a que las acciones terminen.

Tres capacidades clave (del README oficial):

En total expone más de 60 herramientas MCP organizadas por categorías:

3. Instalación, configuración base y primer prompt

Requisitos mínimos: Node.js LTS, npm y Google Chrome (stable o Chrome for Testing). Solo se soportan oficialmente Chrome y Chrome for Testing; otros navegadores Chromium pueden funcionar pero sin garantías.

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    }
  }
}

Check the performance of https://developers.chrome.com

El cliente debería abrir Chrome y grabar una traza de rendimiento. El navegador arranca bajo demanda: conectar el servidor MCP no lo abre; se abre en cuanto se llama a una herramienta que lo necesita.

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest", "--no-usage-statistics", "--no-performance-crux"]
    }
  }
}

La recogida también se desactiva si existe la variable CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS o CI. Y CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS desactiva el aviso periódico de versiones nuevas.

4. Conecta tu agente: Claude Code, Cursor, VS Code y más

Cada cliente MCP tiene su vía de instalación. La guía oficial cubre Antigravity, Bob, Claude Code, Cline, Cursor, Devin CLI, Gemini CLI, Copilot/VS Code y más. Los ejemplos más usados:

Claude Code

claude mcp add chrome-devtools --scope user npx chrome-devtools-mcp@latest

Cursor

Ve a Cursor Settings → MCP → New MCP Server y pega la configuración base del paso 3 (command npx, args ["-y", "chrome-devtools-mcp@latest"]).

VS Code / Copilot

Puedes usar el botón "Install Server" de la documentación (enlace vscode://) o el CLI:

code --add-mcp '{"name":"io.github.ChromeDevTools/chrome-devtools-mcp","command":"npx","args":["-y","chrome-devtools-mcp"],"env":{}}'

Antigravity (Google)

Instala el servidor custom y, como Antigravity ya trae navegador integrado, conéctalo a él en vez de lanzar otro:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["chrome-devtools-mcp@latest", "--browserUrl", "http://127.0.0.1:9222"]
    }
  }
}

En ese modo el servidor no lanza Chrome: debes arrancar el navegador de Antigravity primero (icono de Chrome arriba a la derecha).

5. Navegación y modo slim: las primeras herramientas

El paquete incluye una CLI experimental (chrome-devtools) ideal para depurar o para que un agente genere scripts de automatización. Se instala global y actúa de cliente contra un daemon en segundo plano:

npm i chrome-devtools-mcp@latest -g
chrome-devtools status   # comprueba si el daemon está vivo

El daemon se arranca solo en la primera llamada y conserva el estado del navegador (pestañas, cookies) entre comandos:

# Abre una página nueva
chrome-devtools new_page "https://example.com"

# Navega la página 1 a otra URL
chrome-devtools navigate_page 1 --url "https://web.dev"

# Screenshot de la página 1 a un fichero
chrome-devtools take_screenshot 1 --filePath screenshot.png

# Para cuando termines
chrome-devtools stop

Dentro del agente, las herramientas de navegación equivalentes son new_page, navigate_page (con soporte para back/forward/reload y handleBeforeUnload), list_pages, select_page, close_page y wait_for. Cada página tiene un pageId: las herramientas reciben siempre el id para saber sobre qué pestaña actuar.

Modo slim para tareas básicas

Con --slim --headless el servidor expone solo tres herramientas — navigate, evaluate y screenshot — perfectas cuando el agente solo necesita "mirar" una web sin tocar nada:

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest", "--slim", "--headless"]
    }
  }
}

6. Automatización de input: clics, formularios y teclado

Aquí es donde el agente deja de ser un lector y empieza a usar la web. El patrón central: el agente toma un snapshot de accesibilidad (take_snapshot), que devuelve los elementos de la página con un identificador único (uid), y luego actúa sobre esos uids.

# 1. Toma el snapshot: cada elemento tiene un uid (p.ej. "input-uid-456")
take_snapshot(pageId=1)

# 2. Rellena un campo del formulario
fill(pageId=1, uid="input-uid-456", value="mi-busqueda")

# 3. Haz clic en el botón de enviar
click(pageId=1, uid="button-uid-789")

Para formularios con varios campos, la documentación recomienda siempre fill_form antes que varias llamadas a fill/click: es más rápido, más fiable y reduce el número de turnos del agente.

En el CLI se ve igual de directo:

chrome-devtools click 1 "element-uid-123"
chrome-devtools fill 1 "input-uid-456" "search query"

7. Debugging real: consola y red con source maps

El debugging clásico de DevTools — pestañas Console y Network — está expuesto como herramientas que el agente puede consultar cuando algo falla.

Consola

# Lista los mensajes de consola desde la última navegación
list_console_messages(pageId=1, includeStackTraces=true)

# Detalle de un mensaje concreto (con stack trace source-mapped)
get_console_message(pageId=1, msgid=42)

La clave: los stack traces llegan source-mapped, así que el agente ve el error apuntando a tu código fuente (TSX, TS, etc.), no al bundle minificado. Con includePreservedMessages=true ves también los mensajes de las últimas 3 navegaciones.

Red

# Últimas peticiones desde la última navegación
list_network_requests(pageId=1)

# Detalle de una petición: headers, cookies, respuesta
get_network_request(pageId=1, reqid=7)

get_network_request permite inspeccionar headers de la petición (incluida Cookie) y de la respuesta (incluida Set-Cookie y directivas) — justo lo que necesitas para depurar autenticación o CORS.

Inspección directa con JavaScript

# Ejecuta una función dentro de la página; el resultado vuelve como JSON
evaluate_script(pageId=1, function="() => document.title")

El valor devuelto debe ser JSON-serializable. Es la herramienta comodín para leer estado de la app, comprobar variables globales o forzar condiciones.

8. Rendimiento: trazas, Core Web Vitals y Lighthouse

El análisis de rendimiento es la joya del proyecto: usa DevTools para grabar trazas y extraer insights accionables, no solo métricas crudas.

# Empieza a grabar una traza en la página
performance_start_trace(pageId=1)

# ... el agente interactúa, recarga, etc. ...

# Para la traza y recibe los insights
performance_stop_trace(pageId=1)

# Pide detalle de un insight concreto
performance_analyze_insight(insightName="LCPBreakdown")

Los insights cubren los Core Web Vitals (LCP, INP, CLS) y desgloses como DocumentLatency o LCPBreakdown. Además, las URLs de las trazas se envían a la API de CrUX para cruzar los datos de laboratorio con datos reales de usuarios (desactivable con --no-performance-crux).

Lighthouse para el resto

Para accesibilidad, SEO, buenas prácticas y "agentic browsing", la herramienta es lighthouse_audit. Ojo: Lighthouse excluye performance — para eso están las trazas:

# Auditoría Lighthouse en modo navegación (o snapshot)
lighthouse_audit(pageId=1, device="desktop")

Una sesión típica de auditoría con el agente:

• Pide: "Audita el rendimiento de https://mi-sitio.com y dame el top 3 de problemas con su impacto".
• El agente abre la página, graba una traza de carga, recibe insights y te los resume con recomendaciones concretas.
• Si además quieres nota de accesibilidad/SEO, pide una lighthouse_audit sobre la misma URL.

9. Avanzado: emulación, Chrome real y sesiones concurrentes

Cuando dominas lo básico, el servidor tiene un segundo nivel de potencia.

Emulación de dispositivos y condiciones

# Emula modo oscuro, throttling de CPU o un dispositivo concreto
emulate(pageId=1, colorScheme="dark", cpuThrottlingRate=6)

# Cambia el tamaño de la ventana para probar responsive
resize_page(pageId=1, width=390, height=844)

También puedes fijar el viewport inicial de arranque con --viewport=1280x720 (en headless el máximo es 3840x2160).

Conectar a un Chrome que ya está corriendo

En vez de lanzar una instancia nueva, puedes atarte al Chrome del usuario. Dos vías:

• --autoConnect: se conecta automáticamente al Chrome local (Chrome 144+) que tenga activada la depuración remota en chrome://inspect/#remote-debugging. El navegador muestra un diálogo pidiendo permiso.
• --browserUrl/--wsEndpoint: conexión manual a una instancia con puerto de depuración (típico http://127.0.0.1:9222). El endpoint WebSocket se consulta en http://127.0.0.1:9222/json/version (campo webSocketDebuggerUrl).

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["chrome-devtools-mcp@latest", "--browserUrl", "http://127.0.0.1:9222"]
    }
  }
}

Con --wsHeaders puedes añadir headers de autenticación al WebSocket (p.ej. {"Authorization":"Bearer token"}), útil en entornos controlados.

Sesiones concurrentes y estado aislado

Funcionalidades adicionales tras flags: --experimentalVision habilita click_at(x,y) por coordenadas (para modelos computer-use), --memoryDebugging expone análisis de heap snapshots, --categoryExtensions gestiona extensiones de Chrome, --categoryPwa instala/lanza PWAs, --experimentalScreencast graba vídeo de la página (requiere ffmpeg), y hay guía oficial para depurar Chrome en Android.

10. Seguridad, casos de uso y troubleshooting

Superficie y restricciones

El servidor está pensado para agentes locales de confianza, pero ofrece controles para reducir la superficie:

Casos de uso reales

• Testing E2E sin framework: pide al agente que recorra el flujo crítico de tu app tras cada cambio y reporte errores de consola.
• Auditoría de tu landing: rendimiento + Lighthouse + screenshot en móvil/desktop antes de publicar.
• Depuración de incidencias: reproducir un bug reportado, leer la petición fallida y verificar el fix en el mismo chat.
• Automatización personal: rellenar formularios repetitivos, comprobar disponibilidad, extraer datos con evaluate_script.

Troubleshooting rápido

• Error [ERR_MODULE_NOT_FOUND] — caché de npm corrupta o versión antigua: reinstala o usa @latest.
• Target closed — la página se cerró o navegó a una URL bloqueada; revisa --blockedUrlPattern y vuelve a tomar snapshot.
• Depuración remota VM↔host que falla — revisa el port forwarding (guía de remote debugging de Chrome DevTools).
• El CLI se cuelga — chrome-devtools stop y reintenta; para logs verbosos: DEBUG=* chrome-devtools list_pages.
• Chrome crashea en macOS con Web Bluetooth — problema conocido del sandbox; consulta el troubleshooting oficial.