Puppeteer MCP Server

Automatiza interacciones del navegador usando Puppeteer, controlando instancias nuevas o existentes de Chrome.

Documentación

Puppeteer MCP Server

Este servidor MCP proporciona capacidades de automatización de navegador a través de Puppeteer, permitiendo la interacción tanto con nuevas instancias de navegador como con ventanas de Chrome existentes.

Reconocimiento

Este proyecto es una implementación experimental inspirada en @modelcontextprotocol/server-puppeteer. Aunque comparte objetivos y conceptos similares, explora enfoques alternativos para la automatización de navegadores a través del Protocolo de Contexto de Modelo.

Características

Navegar por páginas web
Tomar capturas de pantalla
Hacer clic en elementos
Rellenar formularios
Seleccionar opciones
Pasar el cursor sobre elementos
Ejecutar JavaScript
Gestión inteligente de pestañas de Chrome:
- Conectarse a pestañas activas de Chrome
- Preservar instancias de Chrome existentes
- Manejo inteligente de conexiones

Estructura del Proyecto

/
├── src/
│   ├── config/        # Configuration modules
│   ├── tools/         # Tool definitions and handlers
│   ├── browser/       # Browser connection management
│   ├── types/         # TypeScript type definitions
│   ├── resources/     # Resource handlers
│   └── server.ts      # Server initialization
├── index.ts          # Entry point
└── README.md        # Documentation

Instalación

Opción 1: Instalar desde npm

npm install -g puppeteer-mcp-server

También puedes ejecutarlo directamente sin instalación usando npx:

npx puppeteer-mcp-server

Opción 2: Instalar desde el código fuente

Clona este repositorio o descarga el código fuente
Instala las dependencias:

npm install

Compila el proyecto:

npm run build

Ejecuta el servidor:

npm start

Configuración del Servidor MCP

Para usar esta herramienta con Claude, debes agregarla a tu archivo de configuración de ajustes de MCP.

Para la aplicación de escritorio de Claude

Agrega lo siguiente a tu archivo de configuración de Claude Desktop (ubicado en %APPDATA%\Claude\claude_desktop_config.json en Windows o ~/Library/Application Support/Claude/claude_desktop_config.json en macOS):

Si se instala globalmente mediante npm:

{
  "mcpServers": {
    "puppeteer": {
      "command": "puppeteer-mcp-server",
      "args": [],
      "env": {}
    }
  }
}

Usando npx (sin instalación):

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "puppeteer-mcp-server"],
      "env": {}
    }
  }
}

Si se instala desde el código fuente:

{
  "mcpServers": {
    "puppeteer": {
      "command": "node",
      "args": ["path/to/puppeteer-mcp-server/dist/index.js"],
      "env": {
        "NODE_OPTIONS": "--experimental-modules"
      }
    }
  }
}

Para la extensión de Claude VSCode

Agrega lo siguiente a tu archivo de configuración de MCP de la extensión de Claude VSCode (ubicado en %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json en Windows o ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json en macOS):

Si se instala globalmente mediante npm:

{
  "mcpServers": {
    "puppeteer": {
      "command": "puppeteer-mcp-server",
      "args": [],
      "env": {}
    }
  }
}

Usando npx (sin instalación):

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "puppeteer-mcp-server"],
      "env": {}
    }
  }
}

Si se instala desde el código fuente:

{
  "mcpServers": {
    "puppeteer": {
      "command": "node",
      "args": ["path/to/puppeteer-mcp-server/dist/index.js"],
      "env": {
        "NODE_OPTIONS": "--experimental-modules"
      }
    }
  }
}

Para la instalación desde el código fuente, reemplaza path/to/puppeteer-mcp-server con la ruta real donde instalaste esta herramienta.

Uso

Modo estándar

El servidor lanzará una nueva instancia de navegador por defecto.

Modo de pestaña activa

Para conectarse a una ventana de Chrome existente:

Cierra completamente cualquier instancia de Chrome existente

Lanza Chrome con la depuración remota habilitada:

# Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

# Linux
google-chrome --remote-debugging-port=9222

Navega a la página web deseada en Chrome

Conéctate usando la herramienta puppeteer_connect_active_tab:

{
  "targetUrl": "https://example.com", // Optional: specific tab URL
  "debugPort": 9222 // Optional: defaults to 9222
}

El servidor:

Detectará y se conectará a la instancia de Chrome que se ejecuta con la depuración remota habilitada
Preservará tu instancia de Chrome (no la cerrará)
Encontrará y se conectará a pestañas que no sean de extensiones
Proporcionará mensajes de error claros si la conexión falla

Herramientas disponibles

puppeteer_connect_active_tab

Conéctate a una instancia de Chrome existente con la depuración remota habilitada.

Opcional:
- targetUrl - URL de la pestaña específica a la que conectarse
- debugPort - Puerto de depuración de Chrome (predeterminado: 9222)

puppeteer_navigate

Navega a una URL.

Requerido: url - La URL a la que navegar

puppeteer_screenshot

Toma una captura de pantalla de la página actual o de un elemento específico.

Requerido: name - Nombre para la captura de pantalla
Opcional:
- selector - Selector CSS del elemento a capturar
- width - Ancho en píxeles (predeterminado: 800)
- height - Alto en píxeles (predeterminado: 600)

puppeteer_click

Haz clic en un elemento de la página.

Requerido: selector - Selector CSS del elemento en el que hacer clic

puppeteer_fill

Rellena un campo de entrada.

Requerido:
- selector - Selector CSS del campo de entrada
- value - Texto a introducir

puppeteer_select

Usa menús desplegables.

Requerido:
- selector - Selector CSS del elemento de selección
- value - Valor de la opción a seleccionar

puppeteer_hover

Pasa el cursor sobre elementos.

Requerido: selector - Selector CSS del elemento sobre el que pasar el cursor

puppeteer_evaluate

Ejecuta JavaScript en la consola del navegador.

Requerido: script - Código JavaScript a ejecutar

Consideraciones de seguridad

Al usar la depuración remota:

Habilítala solo en redes de confianza
Usa un puerto de depuración único
Cierra el puerto de depuración cuando no esté en uso
Nunca expongas el puerto de depuración a redes públicas

Registro y depuración

Registro basado en archivos

El servidor implementa un registro exhaustivo usando Winston:

Ubicación: directorio logs/
Patrón de archivo: mcp-puppeteer-YYYY-MM-DD.log
Rotación de registros:
- Rotación diaria
- Tamaño máximo: 20MB por archivo
- Retención: 14 días
- Compresión automática de registros antiguos

Niveles de registro

DEBUG: Información detallada de depuración
INFO: Información operativa general
WARN: Mensajes de advertencia
ERROR: Eventos de error y excepciones

Información registrada

Eventos de inicio/apagado del servidor
Operaciones del navegador (lanzamiento, conexión, cierre)
Intentos y resultados de navegación
Ejecuciones y resultados de herramientas
Detalles de errores con trazas de pila
Salida de la consola del navegador
Uso de recursos (capturas de pantalla, registros de consola)

Manejo de errores

El servidor proporciona mensajes de error detallados para:

Fallos de conexión
Elementos faltantes
Selectores no válidos
Errores de ejecución de JavaScript
Fallos de captura de pantalla

Cada llamada a herramienta devuelve:

Estado de éxito/fallo
Mensaje de error detallado si falla
Datos del resultado de la operación si tiene éxito

Todos los errores también se registran en los archivos de registro con:

Marca de tiempo
Mensaje de error
Traza de pila (cuando esté disponible)
Información de contexto

Contribuciones

¡Las contribuciones son bienvenidas! Por favor, lee nuestras Pautas de contribución para obtener detalles sobre cómo enviar solicitudes de extracción, informar problemas y contribuir al proyecto.

Licencia

Este proyecto está licenciado bajo la Licencia MIT: consulta el archivo LICENSE para obtener más detalles.