Chrome Debug

Automatiza Chrome a través de su puerto de depuración con persistencia de sesión. Requiere que Chrome se inicie con la depuración remota habilitada.

GitHub
10
Prueba este MCPPatrocinado

Documentación

Servidor MCP de Chrome Debug

Idioma: English | 中文

Un servidor de Model Context Protocol (MCP) para la automatización del navegador Chrome mediante el protocolo de depuración, diseñado específicamente para conectarse a los puertos de depuración de Chrome y permitir la automatización del navegador con sesiones de inicio de sesión persistentes.

🎯 Ventajas del Proyecto

🚀 Ventajas Técnicas Principales

  1. 🔧 Despliegue con Cero Dependencias

    • No requiere extensiones de Chrome
    • No necesita aprobación de Chrome Web Store
    • Totalmente autónomo en entornos empresariales

  2. 📦 Compatible con Contenedores

    • Soporte perfecto para despliegue con Docker/Kubernetes
    • Sin problemas de permisos o instalación de extensiones
    • Ideal para arquitectura cloud-native

  3. ⚡ Inicio en Dos Pasos

    # Launch with just two commands
# 1. Start Chrome in debug mode
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug
# 2. Run MCP server
npx chrome-debug-mcp

  4. 🛡️ Seguridad de Nivel Empresarial

    • Basado en el protocolo estándar Chrome DevTools
    • No requiere permisos de extensiones de terceros
    • Operación completamente local

🚀 Inicio Rápido

Opción 1: Uso Directo (Recomendado)

Inicie con npx - no se requiere instalación:

# 1. Start Chrome in debug mode
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

# 2. Run MCP server directly
npx chrome-debug-mcp

Opción 2: Desarrollo Local

git clone https://github.com/rainmenxia/chrome-debug-mcp.git
cd chrome-debug-mcp
npm install
npm run build
npm start

Características Principales

  • ✅ Conexión al Puerto de Depuración de Chrome: Basado en el protocolo estándar Chrome DevTools, sin necesidad de extensiones
  • 🏢 Despliegue de Nivel Empresarial: Despliegue con cero dependencias, sin necesidad de aprobación de Chrome Web Store
  • 📱 Gestión Inteligente de Pestañas: Reutiliza pestañas para los mismos dominios, evita aperturas duplicadas
  • 🖼️ Capturas de Pantalla en Tiempo Real: Capturas automáticas después de cada operación para retroalimentación visual
  • 🌐 Monitoreo de Actividad de Red: Espera automática a que la página termine de cargar
  • 🐳 Soporte Nativo de Docker: Soporte perfecto para instancias de Chrome en contenedores, sin limitaciones de extensiones
  • ⚡ Inicio en Dos Pasos: Inicie Chrome en modo depuración y luego ejecute npx chrome-debug-mcp, sin instalación compleja
  • 🔍 Detección Inteligente del Navegador: Descubre automáticamente instancias de Chrome en entornos locales y Docker

Configuración y Uso

1. Iniciar Chrome en Modo Depuración (Requerido)

El servidor necesita conectarse a una instancia de Chrome con el puerto de depuración habilitado:

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

# Windows
chrome.exe --remote-debugging-port=9222 --user-data-dir=c:\temp\chrome-debug

# Linux
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

Notas Importantes:

  • El parámetro --user-data-dir apunta a un directorio temporal, asegurando que Chrome se inicie en modo depuración
  • Después del inicio, puede iniciar sesión en sitios web normalmente y las sesiones de inicio de sesión se conservarán
  • El servidor reutilizará esta instancia de Chrome, sin necesidad de volver a iniciar sesión

2. Configurar el Cliente MCP

Agregue la siguiente configuración a su cliente MCP:

{
  "mcpServers": {
    "browser-automation": {
      "command": "npx",
      "args": ["chrome-debug-mcp"]
    }
  }
}

¡Eso es todo! Sin instalación, sin descargas, sin configuración compleja de rutas.

💡 Métodos de Instalación Alternativos:

Instalación Global:

npm install -g chrome-debug-mcp

{
  "mcpServers": {
    "browser-automation": {
      "command": "chrome-debug-mcp"
    }
  }
}

Instalación en Proyecto Local:

npm install chrome-debug-mcp

{
  "mcpServers": {
    "browser-automation": {
      "command": "npx",
      "args": ["chrome-debug-mcp"]
    }
  }
}

Herramientas Disponibles

1. launch_browser

Conéctese al puerto de depuración de Chrome e inicialice la sesión del navegador.

{
  "name": "launch_browser",
  "arguments": {
    "remote_host": "http://localhost:9222"  // optional
  }
}

2. navigate_to

Navegue a la URL especificada con gestión inteligente de pestañas.

{
  "name": "navigate_to", 
  "arguments": {
    "url": "https://example.com"
  }
}

3. click

Haga clic en las coordenadas especificadas.

{
  "name": "click",
  "arguments": {
    "coordinate": "100,200"
  }
}

4. type_text

Ingrese contenido de texto.

{
  "name": "type_text",
  "arguments": {
    "text": "Hello World"
  }
}

5. scroll_down / scroll_up

Desplace la página.

{
  "name": "scroll_down",
  "arguments": {}
}

6. hover

Coloque el cursor del mouse en la posición especificada.

{
  "name": "hover",
  "arguments": {
    "coordinate": "100,200"
  }
}

7. resize_browser

Cambie el tamaño de la ventana del navegador.

{
  "name": "resize_browser",
  "arguments": {
    "size": "1200,800"
  }
}

8. get_page_content

Obtenga el contenido HTML actual de la página.

{
  "name": "get_page_content",
  "arguments": {}
}

9. close_browser

Cierre la conexión del navegador.

{
  "name": "close_browser",
  "arguments": {}
}

Casos de Uso Típicos

1. Automatización de Redes Sociales

# Manually log into Twitter/Weibo in Chrome first
# Then use MCP tools for automation
launch_browser -> navigate_to -> click -> type_text

2. Operaciones de Comercio Electrónico

# Keep logged-in state for Taobao/JD
# Automate product search, price monitoring, etc.
launch_browser -> navigate_to -> type_text -> click

3. Extracción de Datos

# Scrape data from login-required websites
# Bypass login verification, direct operations
launch_browser -> navigate_to -> get_page_content

Características Avanzadas

Gestión Inteligente de Pestañas

  • Los mismos dominios (por ejemplo, example.com) reutilizan pestañas existentes
  • Los diferentes dominios crean automáticamente nuevas pestañas
  • Evita aperturas duplicadas de los mismos sitios web

Mecanismos de Espera Automática

  • Monitorea la actividad de red, espera la carga completa de la página
  • Detección de estabilidad del contenido HTML
  • Manejo automático de carga de contenido dinámico

Recuperación de Errores

  • Reconexión automática ante caídas de conexión
  • Almacenamiento en caché de endpoints de conexión exitosos
  • Registros de errores detallados y retroalimentación

Soporte para Entornos Docker

Si Chrome se ejecuta en un contenedor Docker:

# Start Chrome in Docker
docker run -d --name chrome-debug \
  -p 9222:9222 \
  --shm-size=2gb \
  zenika/alpine-chrome \
  --no-sandbox \
  --disable-dev-shm-usage \
  --remote-debugging-address=0.0.0.0 \
  --remote-debugging-port=9222

El servidor descubrirá automáticamente instancias de Chrome en entornos Docker.

Solución de Problemas

Fallo de Conexión con Chrome

  1. Confirme que Chrome se inició con --remote-debugging-port=9222
  2. Verifique si el puerto 9222 está ocupado: lsof -i :9222
  3. Asegúrese de que no haya otras instancias de Chrome en ejecución

Tiempo de Espera Agotado en Operaciones

  1. Verifique la conexión de red
  2. Aumente el tiempo de espera de carga de la página
  3. Confirme que el sitio web de destino sea accesible

Fallo en la Captura de Pantalla

  1. Confirme que la página esté completamente cargada
  2. Verifique la configuración del tamaño de la ventana del navegador
  3. Intente actualizar la página y reintentar la operación

Arquitectura Técnica

MCP Client ←→ stdio ←→ MCP Server ←→ Chrome Debug Port ←→ Chrome Browser
  • Protocolo de Transporte: stdio (entrada/salida estándar)
  • Motor del Navegador: Puppeteer + Chrome DevTools Protocol
  • Método de Conexión: WebSocket (puerto de depuración de Chrome)
  • Formato de Imagen: Codificación base64 WebP/PNG

Desarrollo y Depuración

# Watch mode compilation
npm run dev

# View MCP communication logs
DEBUG=mcp* npm start

Publicación en npm

# Build project
npm run build

# Publish to npm
npm publish

Agradecimientos

La filosofía de diseño y los conceptos principales de este proyecto se inspiraron en el proyecto RooCode. RooCode es una excelente implementación de servidor MCP para automatización de navegador que proporcionó valiosas referencias técnicas y perspectivas de diseño.

Agradecimiento especial al equipo de RooCode por sus contribuciones en las siguientes áreas:

  • 🎯 Integración del Protocolo MCP: Proporcionaron soluciones técnicas para combinar servidores MCP con automatización de navegador
  • 🔗 Conexión del Navegador: Demostraron una elegante gestión de conexión y sesiones del navegador
  • 📋 Diseño de la API de Herramientas: Proporcionaron marcos de referencia para estandarizar operaciones del navegador

Basándose en los cimientos de RooCode, este proyecto se enfoca además en la automatización del navegador con sesiones de inicio de sesión persistentes, logrando capacidades de automatización más prácticas al conectarse a puertos de depuración de Chrome existentes para mantener las sesiones de usuario.

Licencia

Licencia MIT

Ventaja Principal: La mayor característica de este servidor MCP es su capacidad para conectarse a instancias existentes de Chrome y mantener las sesiones de inicio de sesión, lo que lo hace ideal para escenarios de automatización que requieren autenticación de usuario. A través de los puertos de depuración de Chrome, puede tomar el control de sesiones de navegador con sesión de usuario iniciada, logrando una automatización del navegador verdaderamente "con sesión persistente".