Chrome DevTools MCP Server

Un servidor MCP para desarrollo frontend asistido por IA usando Chrome DevTools. Requiere Google Chrome.

GitHub
5
Prueba este MCPPatrocinado

Documentación

Chrome DevTools MCP Server

License: MIT

Un servidor de control de Chrome DevTools basado en el Protocolo de Contexto de Modelos (MCP), que proporciona potentes capacidades de depuración de navegador para el desarrollo frontend asistido por IA.

Características

Este proyecto proporciona un conjunto completo de herramientas de control del navegador Chrome, que permiten a la IA:

  • 🚀 Iniciar y controlar el navegador Chrome - Inicia automáticamente una instancia de Chrome para el entorno de desarrollo
  • 🔗 Conexión remota a CDP - Conéctate a Chrome, Electron u otros programas con núcleo V8 ya en ejecución
  • 🔍 Consulta y análisis del DOM - Obtén la estructura del árbol DOM de la página, consulta elementos específicos
  • 🌐 Monitoreo de solicitudes de red - Captura y analiza en tiempo real todas las solicitudes y respuestas de red
  • 📝 Captura de registros de consola - Obtén toda la salida de la consola, incluidos errores, advertencias y registros
  • 💻 Ejecución de JavaScript - Ejecuta cualquier código JavaScript en el contexto de la página
  • 🎯 Navegación de páginas - Controla el navegador para navegar a una URL específica
  • 📸 Función de captura de pantalla - Captura la pantalla de la página actual
  • ℹ️ Obtención de información de la página - Obtén el título, la URL, los metadatos y otra información de la página
  • 🐛 Depuración con puntos de interrupción de JavaScript - Establece varios tipos de puntos de interrupción, con soporte para puntos de interrupción condicionales
  • 🎮 Control de depuración - Pausar, continuar, ejecutar paso a paso y otras operaciones de depuración

Parte 1: Desarrollo, instalación y puesta en marcha

Requisitos del entorno

  • Python 3.7+
  • Navegador Google Chrome
  • macOS/Linux/Windows

Pasos de instalación

  1. Clona el proyecto:
git clone https://github.com/yourusername/chrome-devtool-mcp.git
cd chrome-devtool-mcp
  1. Crea un entorno virtual (recomendado):
python -m venv venv
source venv/bin/activate  # macOS/Linux
# 或
venv\Scripts\activate  # Windows
  1. Instala las dependencias:
pip install -r requirements.txt

Iniciar el servidor

Usa el siguiente comando para iniciar el servidor:

python src/chrome_devtools_mcp.py

O usa el script de inicio:

./start.sh

El servidor se iniciará en http://localhost:12524.

Puerto personalizado

Si necesitas usar otro puerto, modifica el número de puerto en el script o establece la variable de entorno:

MCP_PORT=8080 python src/chrome_devtools_mcp.py

Parte 2: Guía de integración con Claude Code

Método 1: Usar el archivo de configuración de MCP

  1. Crea o edita el archivo de configuración de MCP de Claude Code:

macOS/Linux:

mkdir -p ~/.config/claude/mcp
nano ~/.config/claude/mcp/chrome-devtools.json

Windows:

mkdir -p $env:APPDATA\claude\mcp
notepad $env:APPDATA\claude\mcp\chrome-devtools.json
  1. Agrega la siguiente configuración:
{
  "mcpServers": {
    "chrome-devtools": {
      "command": "python",
      "args": ["/path/to/chrome-devtool-mcp/mcp_server.py"],
      "env": {}
    }
  }
}
  1. Reinicia Claude Code para cargar la configuración.

Método 2: Iniciar con un agente ya conectado

Si ya tienes otros servidores MCP en ejecución, puedes agregar el servidor Chrome DevTools de la siguiente manera:

  1. Modifica el archivo de configuración de MCP existente y agrega la configuración de chrome-devtools:
{
  "mcpServers": {
    "existing-server": {
      // ... 现有配置
    },
    "chrome-devtools": {
      "command": "python",
      "args": ["/path/to/chrome-devtool-mcp/mcp_server.py"],
      "env": {}
    }
  }
}
  1. O usa el método de variables de entorno:
export CLAUDE_MCP_CHROME_DEVTOOLS="python /path/to/chrome-devtool-mcp/mcp_server.py"
claude-code

Verificar la integración

En Claude Code, puedes verificar si las herramientas se han integrado correctamente de la siguiente manera:

请列出所有可用的 MCP 工具

Deberías poder ver las siguientes herramientas:

  • launch_chrome
  • connect_remote_chrome
  • connect_websocket_url
  • list_available_targets
  • navigate_to
  • get_dom_tree
  • query_elements
  • get_network_logs
  • get_console_logs
  • execute_javascript
  • take_screenshot
  • get_page_info
  • get_script_sources
  • get_script_source
  • search_in_scripts
  • get_page_functions
  • set_breakpoint
  • list_breakpoints
  • remove_breakpoint
  • get_paused_info
  • resume_execution
  • step_over
  • close_chrome

Parte 3: Guía de integración con Cursor

Método 1: Integración mediante archivo de configuración (recomendado)

  1. Primero asegúrate de que el servidor MCP esté iniciado: 
    python simple_mcp_server.py
# 服务器运行在 http://localhost:12524
  2. Abre la configuración de Cursor ( Cmd+, o Ctrl+,)
  3. Busca "Model Context Protocol" o "MCP"
  4. Agrega lo siguiente en la configuración de MCP: 
    {
  "mcpServers": {
    "chrome-devtools": {
      "command": "python3",
      "args": ["/path/to/chrome-devtool-mcp/src/chrome_devtools_mcp.py"]
    }
  }
}
  5. Reinicia Cursor para cargar las herramientas MCP

Método 2: Configuración con variables de entorno

Si necesitas personalizar el puerto o el host:

  1. Establece las variables de entorno e inicia el servidor: 
    MCP_PORT=8080 MCP_HOST=127.0.0.1 python src/chrome_devtools_mcp.py
  2. Usa el puerto correspondiente en la configuración de Cursor: 
    {
  "mcpServers": {
    "chrome-devtools": {
      "command": "python3",
      "args": ["/path/to/chrome-devtool-mcp/src/chrome_devtools_mcp.py"],
      "env": {
        "MCP_PORT": "8080",
        "MCP_HOST": "127.0.0.1"
      }
    }
  }
}

Verificar la conexión

Después de una conexión exitosa, puedes hacer lo siguiente en Cursor:

  1. Usa el símbolo @ para ver las herramientas MCP disponibles
  2. O pregunta "lista todas las herramientas de Chrome DevTools disponibles"

Deberías poder ver las siguientes herramientas:

  • launch_chrome
  • connect_remote_chrome
  • connect_websocket_url
  • list_available_targets
  • navigate_to
  • get_dom_tree
  • query_elements
  • get_network_logs
  • get_console_logs
  • execute_javascript
  • take_screenshot
  • get_page_info
  • get_script_sources
  • get_script_source
  • search_in_scripts
  • get_page_functions
  • set_breakpoint
  • list_breakpoints
  • remove_breakpoint
  • get_paused_info
  • resume_execution
  • step_over
  • close_chrome

Solución de problemas

Si no puedes conectarte:

  1. Asegúrate de que el servidor esté en ejecución: 
    curl http://localhost:12524/health
  2. Verifica la configuración del firewall para asegurarte de que el puerto 12524 sea accesible
  3. Revisa los registros del servidor para obtener información detallada sobre los errores
  4. Intenta acceder a http://localhost:12524/docs en el navegador para ver la documentación de la API

Ejemplos de uso

Flujo de uso básico

  1. Iniciar Chrome:
使用 launch_chrome 工具启动一个 Chrome 浏览器实例
  1. Navegar a la página de destino:
使用 navigate_to 工具访问 http://localhost:3000
  1. Inspeccionar la estructura de la página:
使用 get_dom_tree 工具获取页面的 DOM 结构
  1. Consultar elementos específicos:
使用 query_elements 工具查找所有 class 为 "button" 的元素
  1. Monitorear solicitudes de red:
使用 get_network_logs 工具查看所有 API 请求
  1. Ejecutar JavaScript:
使用 execute_javascript 工具在页面上执行 console.log('Hello from AI!')

Escenarios avanzados de depuración

Escenario 1: Depurar el estado de una aplicación React

1. 启动 Chrome 并导航到 React 应用
2. 使用 execute_javascript 执行：
   window.__REACT_DEVTOOLS_GLOBAL_HOOK__.renderers.values().next().value.findFiberByHostInstance(document.querySelector('#root'))._debugOwner.stateNode.state
3. 分析返回的状态数据

Escenario 2: Monitorear y analizar llamadas a la API

1. 清空网络日志
2. 触发应用中的某个操作
3. 使用 get_network_logs 筛选特定 API 端点
4. 分析请求和响应数据

Escenario 3: Análisis de rendimiento

1. 使用 execute_javascript 执行 performance.mark('start')
2. 执行一系列操作
3. 使用 execute_javascript 执行 performance.mark('end') 和 performance.measure('operation', 'start', 'end')
4. 获取性能数据

Escenario 4: Depurar el evento de clic en el botón de inicio de sesión

1. 使用 connect_remote_chrome 连接到已运行的应用
2. 使用 query_elements 找到登录按钮选择器（如 '#login-btn'）
3. 使用 set_breakpoint('dom', '#login-btn') 在登录按钮上设置断点
4. 点击登录按钮，调试器会暂停
5. 使用 get_console_logs 查看控制台输出
6. 使用 get_paused_info 查看暂停位置和调用栈
7. 使用 resume_execution 继续执行

Escenario 5: Depurar una aplicación Electron remota

1. 启动 Electron 应用时添加 --remote-debugging-port=9222 参数
2. 使用 connect_remote_chrome('localhost', 9222) 连接
3. 使用各种调试工具进行分析
4. 设置断点并调试特定功能

Escenario 6: Cambiar entre múltiples pestañas

1. 使用 list_available_targets() 列出所有可用的标签页
2. 选择目标标签页的 webSocketDebuggerUrl
3. 使用 connect_websocket_url(ws_url) 切换到该标签页
4. 现在所有操作都会在新的标签页上执行

Código de ejemplo:

# 列出所有标签页
targets = list_available_targets()
# 选择第二个标签页
ws_url = targets['data']['targets'][1]['webSocketDebuggerUrl']
# 切换到该标签页
connect_websocket_url(ws_url)

Descripción detallada de las herramientas de la API

launch_chrome

Inicia una instancia del navegador Chrome, con soporte para modo headless.

Parámetros:

  • headless (bool): Si se ejecuta en modo headless, el valor predeterminado es false
  • port (int): Puerto de depuración remota, el valor predeterminado es 9222

connect_remote_chrome

Conéctate a una instancia remota de Chrome/Chromium (como una aplicación Electron).

Parámetros:

  • host (str): Dirección del host remoto, el valor predeterminado es localhost
  • port (int): Puerto de depuración remota, el valor predeterminado es 9222

connect_websocket_url

Usa directamente una URL de WebSocket para conectarte a una sesión de depuración específica.

Parámetros:

  • ws_url (str): URL del depurador WebSocket, como 'ws://localhost:9222/devtools/page/ABC123'

Escenarios de uso:

  • Cambiar entre diferentes pestañas/páginas
  • Conectarse a una sesión de depuración específica
  • URL de WebSocket obtenida de otras herramientas

list_available_targets

Enumera todas las pestañas/páginas de Chrome disponibles y sus URL de WebSocket.

Parámetros:

  • host (str): Dirección del host de Chrome, el valor predeterminado es localhost
  • port (int): Puerto de depuración de Chrome, el valor predeterminado es 9222

navigate_to

Navega a una URL específica.

Parámetros:

  • url (str): URL de destino

get_dom_tree

Obtiene la estructura del árbol DOM de la página actual.

Parámetros:

  • depth (int): Profundidad máxima del árbol DOM, el valor predeterminado es 3

query_elements

Consulta elementos del DOM usando selectores CSS.

Parámetros:

  • selector (str): Selector CSS

get_network_logs

Obtiene los registros de solicitudes de red.

Parámetros:

  • filter_url (str, opcional): Patrón de filtro de URL

get_console_logs

Obtiene los registros de la consola.

Parámetros:

  • level (str, opcional): Filtro por nivel de registro (error, warning, log, info)

execute_javascript

Ejecuta código JavaScript en el contexto de la página.

Parámetros:

  • code (str): Código JavaScript a ejecutar

take_screenshot

Captura una captura de pantalla de la página actual.

Parámetros:

  • full_page (bool): Si se captura toda la página, el valor predeterminado es false

get_page_info

Obtiene la información básica de la página actual.

Sin parámetros.

close_chrome

Cierra la instancia del navegador Chrome.

Sin parámetros.

set_breakpoint

Establece puntos de interrupción de JavaScript. Admite puntos de interrupción tradicionales y puntos de interrupción de registro (logpoint).

Parámetros:

  • breakpoint_type (str): Tipo de punto de interrupción - 'dom', 'event', 'function', 'xhr', 'line', 'logpoint'
  • target (str): Objetivo del punto de interrupción (como selector DOM, nombre de función, URL:número de línea)
  • options (dict, opcional): Opciones adicionales
    • condition: Expresión condicional, solo se activa cuando la condición es verdadera
      • logMessage: Mensaje de registro (para puntos de interrupción de registro)
      • pause: Si se pausa la ejecución (predeterminado: false para logpoint, true para otros)

Ejemplos:

  • Punto de interrupción DOM: set_breakpoint('dom', '#login-button')
  • Punto de interrupción de función: set_breakpoint('function', 'handleLogin')
  • Punto de interrupción de línea: set_breakpoint('line', 'app.js:42')
  • Punto de interrupción XHR: set_breakpoint('xhr', '/api/login')
  • Punto de interrupción de registro: set_breakpoint('function', 'processData', {'logMessage': 'Processing data...', 'pause': False})
  • Punto de interrupción de registro condicional: set_breakpoint('function', 'validate', {'condition': 'value < 0', 'logMessage': 'Invalid value', 'pause': False})

list_breakpoints

Enumera todos los puntos de interrupción activos.

Sin parámetros.

remove_breakpoint

Elimina un punto de interrupción específico.

Parámetros:

  • breakpoint_id (str): ID del punto de interrupción

get_paused_info

Obtiene la información cuando el depurador está en pausa.

Sin parámetros.

resume_execution

Reanuda la ejecución desde un punto de interrupción.

Sin parámetros.

step_over

Salta la línea actual paso a paso.

Sin parámetros.

get_script_sources

Obtiene la lista de todas las fuentes de JavaScript cargadas en la página actual.

Sin parámetros.

Devuelve:

  • scripts: Lista de scripts, que incluye scriptId, url, startLine, endLine
  • count: Número total de scripts

get_script_source

Obtiene el código fuente de un script específico.

Parámetros:

  • script_id (str): ID del script (obtenido de get_script_sources)

search_in_scripts

Busca funciones, clases o texto en todos los scripts cargados.

Parámetros:

  • pattern (str): Patrón de búsqueda (como nombre de función, nombre de clase, texto)
  • search_type (str): Tipo de búsqueda - 'function', 'class', 'variable', 'text'

get_page_functions

Obtiene todas las funciones definidas en la página.

Sin parámetros.

Solución de problemas

Chrome no puede iniciarse

  1. Asegúrate de que Chrome esté instalado
  2. Verifica si el puerto 9222 está en uso: 
    lsof -i :9222  # macOS/Linux
netstat -an | findstr 9222  # Windows

Error de conexión WebSocket

  1. Asegúrate de que Chrome se haya iniciado en modo de depuración
  2. Verifica la configuración del firewall
  3. Intenta usar un puerto diferente

Herramientas MCP no reconocidas

  1. Asegúrate de que el servidor MCP esté en ejecución
  2. Verifica que la ruta del archivo de configuración sea correcta
  3. Reinicia Claude Code o Cursor

Guía de contribución

¡Las solicitudes de extracción (Pull Requests) y los informes de problemas (Issues) son bienvenidos!

Licencia

Este proyecto está bajo la Licencia MIT de código abierto.

Licencia MIT: consulta el archivo LICENSE para obtener más detalles.

Esta licencia le permite:

Siempre que usted:

  • 📄 Incluya el aviso de derechos de autor y la declaración de licencia
  • 📝 Documente los cambios realizados (si los hay)