Chrome Debug MCP Server

Automatiza tu navegador conectándote al puerto de depuración de Chrome, preservando tu estado de inicio de sesión.

GitHub
10

Documentación

Chrome Debug MCP Server

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. 🔧 Implementación 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 implementación 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
    • Sin permisos de extensiones de terceros
    • Operación completamente local

🚀 Inicio Rápido

Opción 1: Uso Directo (Recomendado)

Inicie con npx - no 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 extensiones
  • 🏢 Implementación de Nivel Empresarial: Implementación 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
  • 🖼️ Retroalimentación de Capturas en Tiempo Real: Capturas automáticas después de cada operación para retroalimentación visual
  • 🌐 Monitoreo de Actividad de Red: Espera automática para la carga completa de la página
  • 🐳 Soporte Nativo de Docker: Soporte perfecto para instancias de Chrome en contenedores, sin limitaciones de extensiones
  • ⚡ Inicio en Dos Pasos: Inicie Chrome en modo de depuración y luego ejecute npx chrome-debug-mcp, sin instalación compleja
  • 🔍 Descubrimiento Inteligente del Navegador: Detecta automáticamente instancias de Chrome en entornos locales y Docker

Configuración y Uso

1. Iniciar Chrome en Modo de 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 de 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

Desplácese por la página.

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

6. hover

Coloque el cursor 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

Funciones Avanzadas

Gestión Inteligente de Pestañas

  • Los mismos dominios (por ejemplo, example.com) reutilizan pestañas existentes
  • 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 la carga de contenido dinámico

Recuperación de Errores

  • Reconexión automática en caso de 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 en la 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 fueron inspirados por el proyecto RooCode. RooCode es una excelente implementación de servidor MCP de 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 conexión elegante del navegador y gestión de sesiones
  • 📋 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 adicionalmente 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 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 iniciada, logrando una automatización del navegador verdaderamente "con sesión persistente".