chrome-debugger-mcp

English | 中文

English

Un servidor MCP para depuración de Chrome basada en puntos de interrupción.

chrome-debugger-mcp expone primitivas del Chrome DevTools Protocol como herramientas MCP para que un agente de IA pueda conectarse a una pestaña real de Chrome, pausar la ejecución, inspeccionar valores de ámbito, evaluar expresiones dentro del marco de llamada actual y avanzar por el código con hechos reales de ejecución en lugar de adivinar a partir del código fuente estático.

No es un servidor de automatización de navegador genérico. El foco está en la depuración en tiempo de ejecución.

Capacidades principales

• Conectarse a una pestaña real de Chrome mediante CDP tras la confirmación explícita del usuario

• Pausar en puntos de interrupción o en sentencias debugger; y esperar la pausa exacta que esperas

• Leer valores de ámbito local, de cierre y de módulo desde el marco pausado

• Evaluar JavaScript en el marco de llamada actual y avanzar la ejecución paso a paso

• Reanudar limpiamente para que el agente pueda continuar con valores reales de ejecución

Demostración

Demostración: el agente lanza Chrome, espera un punto de interrupción, inspecciona variables de ámbito reales y continúa con hechos de ejecución en lugar de adivinar.

Configuración del cliente MCP

Usar el paquete publicado

{
  "mcpServers": {
    "chrome-debugger": {
      "command": "npx",
      "args": ["-y", "chrome-debugger-mcp"]
    }
  }
}

Instalación

Desde npm

npx -y chrome-debugger-mcp

O instalarlo globalmente:

npm install -g chrome-debugger-mcp

Desde el código fuente

pnpm install
pnpm build
node dist/index.js

Otros aspectos destacados

• Lanzar una instancia de Chrome dedicada con depuración remota habilitada

• Establecer y eliminar puntos de interrupción de DevTools sin editar el código fuente

• Recargar la página mediante CDP para que los puntos de interrupción se vinculen de forma fiable tras la navegación

• Sondeo del estado del depurador cuando el cliente MCP tiene tiempos de espera de solicitud cortos

• Emitir payloads _ui y mensajes de registro que los clientes puedan mostrar al usuario

Por qué ayuda

Muchas herramientas MCP centradas en el navegador son sólidas en la interacción con DOM y la inspección de red, pero débiles en la depuración en tiempo de ejecución. Este servidor ofrece al cliente MCP el bucle que normalmente usarías en Chrome DevTools: conectar a la pestaña correcta, pausar en el momento adecuado, inspeccionar valores reales, avanzar si es necesario y reanudar limpiamente.

También añade salvaguardas que evitan errores comunes del agente:

• adivinar a qué pestaña conectarse

• concluir el comportamiento sin inspeccionar valores de ejecución

• terminar el turno entre reloadPage() y waitForSpecificPause()

Requisitos

• Google Chrome instalado localmente

• Un cliente MCP que admita servidores stdio y llamadas a herramientas

• Acceso a la aplicación que quieres depurar

• Acceso local al código fuente si planeas insertar sentencias debugger; temporales

Modelo de herramientas

El servidor se ejecuta sobre stdio y expone herramientas MCP. Las herramientas más importantes son:

• startDebuggingSession: devuelve el flujo de depuración recomendado y las reglas críticas para el comportamiento del agente

• launchChrome: lanza una instancia de Chrome dedicada con depuración remota habilitada

• listTargets: lista las pestañas de Chrome disponibles y exige que el usuario elija una

• connect: se conecta a la pestaña confirmada

• setBreakpoint: crea un punto de interrupción CDP sin modificar archivos fuente

• removeBreakpoint: elimina un punto de interrupción creado por setBreakpoint

• reloadPage: recarga la página actual mediante CDP

• waitForSpecificPause: espera la siguiente pausa y comprueba si coincide con un archivo y línea objetivo

• waitForPause: espera cualquier pausa sin coincidencia de ubicación

• getScopeVariables: lee valores de ámbito local, de cierre y de módulo desde el marco pausado

• evaluate: ejecuta JavaScript en el marco de llamada pausado

• stepInto, stepOver, stepOut: control de ejecución estándar

• resume: reanuda la ejecución después de la inspección

• getStatus: sondeo no bloqueante del estado conectado o pausado

• forcePause: solicita una pausa en la siguiente sentencia JavaScript

Flujo de trabajo recomendado

Para clientes de IA, el flujo previsto es:

1. Llama a startDebuggingSession().

2. Llama a launchChrome() o usa una instancia de Chrome ya en ejecución con un puerto CDP.

3. Llama a listTargets() y muestra la lista completa de pestañas al usuario.

4. Espera a que el usuario confirme la URL exacta de la página.

5. Llama a connect({ targetUrl }).

6. Inserta una sentencia debugger; temporal en el código fuente local, o llama a setBreakpoint().

7. Llama a reloadPage().

8. Llama inmediatamente a waitForSpecificPause() en el mismo turno.

9. Llama a getScopeVariables() y evaluate() para inspeccionar los valores de ejecución.

10. Avanza si es necesario con stepInto(), stepOver() o stepOut().

11. Llama a resume().

12. Elimina cualquier sentencia debugger; temporal del código fuente.

Reglas importantes para autores de agentes

Este servidor está diseñado para agentes que usan herramientas, no solo para humanos. Si lo integras en un cliente MCP, ten en cuenta estas reglas:

• Nunca omitas listTargets().

• Nunca adivines la URL objetivo, incluso si solo hay una pestaña abierta.

• Espera siempre la confirmación explícita del usuario antes de connect().

• Después de reloadPage(), llama inmediatamente a waitForSpecificPause() o waitForPause() en el mismo turno.

• No expliques el comportamiento a partir del código estático cuando los valores de ejecución se puedan inspeccionar directamente.

• Siempre llama a resume() después de la inspección.

• Si añadiste sentencias debugger; temporales al código fuente, elimínalas antes de terminar.

Cómo coincide waitForSpecificPause

waitForSpecificPause es la primitiva de espera preferida porque es más fiable que esperar una pausa arbitraria.

Coincide con una pausa usando dos estrategias:

1. Fragmento de URL más tolerancia de línea

2. Fragmento de URL más motivo de pausa debugger-statement

La segunda vía es importante cuando los mapas de código, la transpilación o el empaquetado desplazan los números de línea compilados respecto a los números de línea del editor.

Secuencia de herramientas de ejemplo

Un agente que depura una aplicación Vite local podría hacer algo como esto:

1. launchChrome({ dryRun: true })

2. launchChrome()

3. listTargets()

4. Esperar a que el usuario confirme http://127.0.0.1:5173

5. connect({ targetUrl: "127.0.0.1:5173" })

6. Insertar debugger; en App.jsx

7. reloadPage()

8. waitForSpecificPause({ urlFragment: "App.jsx", line: 62, actionHint: "click the Refetch payloads button" })

9. getScopeVariables()

10. evaluate({ expression: "payload.modules" })

11. resume()

Comportamiento de lanzamiento de Chrome

launchChrome() usa un perfil dedicado para no interferir con la sesión normal del navegador del usuario.

Valores predeterminados:

• puerto de depuración remota: 9222

• directorio de perfil: ~/.chrome-debug-profile

Ubicaciones esperadas del binario de Chrome:

• macOS: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome

• Linux: google-chrome

• Windows: C:\Program Files\Google\Chrome\Application\chrome.exe

Si el lanzamiento automático falla, la herramienta devuelve un comando que el usuario puede ejecutar manualmente.

Entorno de pruebas local

Este repositorio incluye una aplicación de prueba desechable en test/ para que puedas probar el servidor de depuración con un flujo de navegador realista.

Iniciar el servicio simulado

cd test/service
node src/server.js

El servicio escucha en http://127.0.0.1:3030.

Iniciar la aplicación web

cd test/web
pnpm install
pnpm dev

La aplicación web se ejecuta en http://127.0.0.1:5173.

Lugares útiles para pausar:

• test/web/src/App.jsx dentro de loadWorkbench

• test/web/src/App.jsx dentro de loadModuleDetail

• test/web/src/App.jsx alrededor de las secciones de detalle sin terminar

Áreas de payload de ejecución que vale la pena inspeccionar:

• summaryCards

• modules

• apiContracts

• nextActions

• responseShape

Solución de problemas

No se encontraron objetivos

Asegúrate de que Chrome se esté ejecutando con --remote-debugging-port=9222 y de que la página objetivo esté abierta.

Más de una pestaña coincide con targetUrl

Pasa una subcadena más específica para que la coincidencia sea única.

waitForPause o waitForSpecificPause agota el tiempo de espera

Esto puede ocurrir cuando:

• la acción de la página nunca se activó

• se estableció el punto de interrupción incorrecto

• el propio cliente MCP tiene un tiempo de espera de solicitud más corto que la llamada a la herramienta

Si tu cliente agota el tiempo de espera rápidamente, usa getStatus() para sondeo o aumenta el tiempo de espera del cliente.

El número de línea pausado no coincide con la línea del editor

Los empaquetadores y transpiladores pueden desplazar los números de línea compilados. Usa waitForSpecificPause() y confía en la coincidencia de fragmentos de URL más la semántica de debugger-statement.

Chrome no se lanza automáticamente

La máquina puede usar una ruta de instalación de Chrome no predeterminada. Ejecuta el comando de lanzamiento devuelto manualmente o ajusta la implementación para que coincida con tu entorno.

Desarrollo

pnpm install
pnpm build
node dist/index.js

La implementación se encuentra en:

• src/index.ts: definiciones de herramientas MCP y sugerencias de flujo de trabajo para el usuario

• src/chrome-manager.ts: integración del Chrome DevTools Protocol y gestión del estado del depurador

Licencia

MIT

Related MCP server: Chrome DevTools MCP

中文

一个面向 Chrome 断点调试的 MCP Server。

chrome-debugger-mcp 把 Chrome DevTools Protocol 的核心调试能力暴露为 MCP 工具，让 AI agent 可以连接真实的 Chrome 标签页，在运行时暂停执行、读取作用域变量、在当前调用帧中执行表达式、单步跟踪代码，并基于真实值继续任务，而不是只靠静态源码猜测行为。

它不是通用浏览器自动化工具。它的重点是运行时调试。

核心能力

• 在用户明确确认后，通过 CDP 连接真实的 Chrome 标签页

• 在断点或 debugger; 命中时暂停，并等待指定文件和行附近的 pause

• 读取当前暂停帧中的 local、closure、module 作用域变量

• 在当前调用帧里执行 JavaScript，并继续单步跟踪

• 检查完成后恢复执行，让 agent 基于真实运行时值继续工作

功能演示

演示流程：agent 拉起 Chrome，等待断点命中，读取真实作用域变量，再基于运行时事实继续执行，而不是靠猜测推进。

MCP 客户端配置

使用已发布包

{
  "mcpServers": {
    "chrome-debugger": {
      "command": "npx",
      "args": ["-y", "chrome-debugger-mcp"]
    }
  }
}

安装方式

从 npm 使用

npx -y chrome-debugger-mcp

也可以全局安装：

npm install -g chrome-debugger-mcp

从源码运行

pnpm install
pnpm build
node dist/index.js

其他特点

• 启动带远程调试端口的独立 Chrome 实例

• 无需修改源码即可设置和移除断点

• 通过 CDP 重载页面，确保跳转后断点可靠绑定

• 当 MCP 客户端请求超时较短时，可轮询调试器状态

• 输出 _ui 结果和 logging 消息，方便客户端展示给用户

为什么适合这个场景

很多浏览器方向的 MCP 工具更擅长 DOM 操作和网络请求观察，但不擅长回答运行时调试问题。这个服务补上的是 Chrome DevTools 里最关键的那条链路：连接正确标签页、在正确时机暂停、读取真实值、必要时单步跟踪、最后恢复执行。

它也内置了几条 guardrails，避免 agent 出现这些常见错误：

• 猜测应该连接哪个标签页

• 没看运行时值就直接下结论

• 在 reloadPage() 和 waitForSpecificPause() 之间错误地结束当前轮次

运行要求

• 本机安装了 Google Chrome

• 使用支持 stdio MCP server 和工具调用的 MCP 客户端

• 可以访问你要调试的应用

• 如果要插入临时 debugger;，需要能访问本地源码

工具模型

这个服务通过 stdio 运行，并暴露一组 MCP tools。最核心的工具有：

• startDebuggingSession：返回推荐调试流程和 agent 行为约束

• launchChrome：启动带远程调试能力的独立 Chrome 实例

• listTargets：列出可调试标签页，并要求用户做选择

• connect：连接到已确认的目标标签页

• setBreakpoint：在不改源码的情况下通过 CDP 设置断点

• removeBreakpoint：移除通过 setBreakpoint 创建的断点

• reloadPage：通过 CDP 重载当前页面

• waitForSpecificPause：等待下一次暂停，并判断是否命中目标文件和行

• waitForPause：不做位置匹配，等待任意暂停

• getScopeVariables：读取当前暂停帧中的局部、闭包、模块作用域变量

• evaluate：在暂停调用帧中执行 JavaScript

• stepInto、stepOver、stepOut：标准单步控制

• resume：检查完毕后恢复执行

• getStatus：非阻塞方式查询是否已连接、是否已暂停

• forcePause：请求在下一条 JavaScript 语句处暂停

推荐工作流

对于 AI 客户端，建议流程是：

1. 调用 startDebuggingSession()。

2. 调用 launchChrome()，或直接复用已经开启 CDP 端口的 Chrome。

3. 调用 listTargets()，并把完整标签页列表展示给用户。

4. 等待用户明确确认要调试的页面 URL。

5. 调用 connect({ targetUrl })。

6. 在本地源码插入临时 debugger;，或者调用 setBreakpoint()。

7. 调用 reloadPage()。

8. 在同一轮里立刻调用 waitForSpecificPause()。

9. 调用 getScopeVariables() 和 evaluate() 检查运行时值。

10. 必要时使用 stepInto()、stepOver()、stepOut() 继续跟踪。

11. 调用 resume()。

12. 删除源码里临时加入的 debugger;。

给 Agent 作者的重要规则

这个服务首先是为会调用工具的 agent 设计的，而不仅仅是给人手动点工具用。如果你要把它接入自己的 MCP 客户端，建议遵守这些规则：

• 不要跳过 listTargets()。

• 即使只看到一个标签页，也不要猜测目标 URL。

• 一定要等用户明确确认后再调用 connect()。

• 调用 reloadPage() 后，必须在同一轮里立刻调用 waitForSpecificPause() 或 waitForPause()。

• 能读取运行时值时，不要只根据静态代码解释行为。

• 检查完之后一定要 resume()。

• 如果向源码里插入了临时 debugger;，结束前要清理掉。

waitForSpecificPause 如何匹配

waitForSpecificPause 是首选的等待工具，因为它比“等待任意暂停”更可靠。

它有两层匹配策略：

1. URL 片段加行号容差

2. URL 片段加 debugger-statement 暂停原因

第二层匹配对经过 source map、转译、打包后的代码尤其重要，因为编译后的行号可能和编辑器行号不完全一致。

调用序列示例

一个 agent 调试本地 Vite 应用时，调用顺序大致会像这样：

1. launchChrome({ dryRun: true })

2. launchChrome()

3. listTargets()

4. 等用户确认 http://127.0.0.1:5173

5. connect({ targetUrl: "127.0.0.1:5173" })

6. 在 App.jsx 插入 debugger;

7. reloadPage()

8. waitForSpecificPause({ urlFragment: "App.jsx", line: 62, actionHint: "click the Refetch payloads button" })

9. getScopeVariables()

10. evaluate({ expression: "payload.modules" })

11. resume()

Chrome 启动行为

launchChrome() 会使用独立 profile，不会影响用户平时正在用的浏览器会话。

默认值：

• 远程调试端口：9222

• profile 目录：~/.chrome-debug-profile

默认 Chrome 可执行文件路径：

• macOS: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome

• Linux: google-chrome

• Windows: C:\Program Files\Google\Chrome\Application\chrome.exe

如果自动启动失败，工具会返回一个命令，用户可手动运行。

本地 Playground

本仓库包含一个可丢弃的测试应用，位于 test/ 下，你可以用它来对真实的浏览器工作流进行调试。

启动 mock 服务

cd test/service
node src/server.js

服务监听在 http://127.0.0.1:3030。

启动 web 应用

cd test/web
pnpm install
pnpm dev

web 应用运行在 http://127.0.0.1:5173。

有用的暂停位置：

• test/web/src/App.jsx 内的 loadWorkbench

• test/web/src/App.jsx 内的 loadModuleDetail

• test/web/src/App.jsx 中未完成的 detail 部分附近

值得检查的运行时 payload 区域：

• summaryCards

• modules

• apiContracts

• nextActions

• responseShape

故障排查

没有找到目标

确保 Chrome 以 --remote-debugging-port=9222 运行，并且目标页面已打开。

多个标签页匹配 targetUrl

传入更具体的子串，使匹配唯一。

waitForPause 或 waitForSpecificPause 超时

可能的原因：

• 页面操作从未触发

• 设置了错误的断点

• MCP 客户端本身的请求超时比工具调用更短

如果你的客户端超时很快，请使用 getStatus() 轮询或增加客户端超时。

暂停的行号与编辑器行号不匹配

打包器和转译器可能会移动编译后的行号。请使用 waitForSpecificPause()，并依赖 URL 片段匹配加上 debugger-statement 语义。

Chrome 无法自动启动

机器可能使用了非默认的 Chrome 安装路径。请手动运行返回的启动命令，或调整实现以匹配你的环境。

开发

pnpm install
pnpm build
node dist/index.js

实现位于：

• src/index.ts：MCP 工具定义和面向用户的工作流提示

• src/chrome-manager.ts：Chrome DevTools Protocol 集成和调试器状态管理

许可证

MIT

• macOS：/Applications/Google Chrome.app/Contents/MacOS/Google Chrome

• Linux：google-chrome

• Windows：C:\Program Files\Google\Chrome\Application\chrome.exe

Si el inicio automático falla, la herramienta devuelve un comando de inicio que el usuario puede ejecutar manualmente.

Playground local

El repositorio incluye una aplicación de prueba desechable en el directorio test/. Puedes usarla directamente para verificar el flujo completo de este MCP de depuración.

Iniciar el mock service

cd test/service
node src/server.js

El servicio escucha en http://127.0.0.1:3030.

Iniciar la web app

cd test/web
pnpm install
pnpm dev

La aplicación web se ejecuta en http://127.0.0.1:5173.

Ubicaciones recomendadas para poner puntos de interrupción:

• loadWorkbench en test/web/src/App.jsx

• loadModuleDetail en test/web/src/App.jsx

• Cerca de la zona detail aún sin terminar en test/web/src/App.jsx

Campos del payload que merece la pena inspeccionar en tiempo de ejecución:

• summaryCards

• modules

• apiContracts

• nextActions

• responseShape

Solución de problemas

No se encuentran targets

Confirma que Chrome se ha iniciado con --remote-debugging-port=9222 y que la página de destino ya está abierta.

targetUrl coincide con varias pestañas

Pasa una subcadena de URL más específica para garantizar que la coincidencia sea única.

waitForPause o waitForSpecificPause agota el tiempo de espera

Las causas más comunes son:

• La acción de la página no se ha activado realmente

• La ubicación del punto de interrupción no es la correcta

• El tiempo de espera de solicitud del propio cliente MCP es más corto que la llamada a la herramienta

Si el tiempo de espera del cliente es corto, puedes usar getStatus() con sondeo o aumentar el tiempo de espera del cliente.

Los números de línea en pausa no coinciden con el editor

El empaquetado y la transpilación provocan desplazamientos en los números de línea compilados. Usa preferentemente waitForSpecificPause() y confía en la coincidencia de fragmentos de URL junto con la coincidencia semántica de debugger-statement.

Chrome no se inicia automáticamente

Es posible que la ruta de instalación de Chrome en la máquina no sea la predeterminada. Puedes ejecutar directamente el comando de inicio devuelto por la herramienta o ajustar la implementación según tu entorno.

Desarrollo

pnpm install
pnpm build
node dist/index.js

Archivos de implementación principales:

• src/index.ts: definición de herramientas MCP y sugerencias de flujo de trabajo orientadas al usuario

• src/chrome-manager.ts: integración con Chrome DevTools Protocol y gestión del estado de depuración

Licencia

MIT