MCP Server Puppeteer

Un servidor MCP (Model Context Protocol) para automatización de navegadores web usando Puppeteer en modo headless.

Descripción

Este servidor MCP proporciona herramientas para controlar navegadores web mediante Puppeteer en modo headless (sin interfaz gráfica), permitiendo a aplicaciones de IA navegar por sitios web, interactuar con elementos, tomar capturas de pantalla y ejecutar JavaScript en el navegador. Optimizado para ejecutarse en servidores sin entorno gráfico.

Características

• Modo Headless: Ejecuta sin interfaz gráfica, ideal para servidores
• Navegación: Navegar a URLs
• Interacción: Hacer clic, rellenar formularios, seleccionar opciones
• Captura: Tomar screenshots de páginas completas o elementos específicos
• Evaluación: Ejecutar código JavaScript en el contexto del navegador
• Hover: Pasar el cursor sobre elementos
• Optimizado para servidores: Configuración optimizada para entornos sin GUI (Docker, VPS, etc.)

Requisitos

• Node.js 17 o superior
• npm o yarn

Instalación

# Instalar dependencias
npm install

# Compilar el proyecto
npm run build

Uso

Con Claude Desktop

Agrega la siguiente configuración a tu archivo de configuración de Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "puppeteer": {
      "command": "node",
      "args": [
        "/RUTA/ABSOLUTA/A/puppeteer/build/index.js"
      ]
    }
  }
}

Con otros clientes MCP

Ejecuta el servidor directamente:

node build/index.js

Herramientas Disponibles

puppeteer_navigate

Navega a una URL en el navegador.

Parámetros:

• url (string, requerido): La URL a la que navegar

Ejemplo:

{
  "url": "https://example.com"
}

puppeteer_click

Hace clic en un elemento usando un selector CSS.

Parámetros:

• selector (string, requerido): Selector CSS del elemento

Ejemplo:

{
  "selector": "button.submit"
}

puppeteer_fill

Rellena un campo de entrada con texto.

Parámetros:

• selector (string, requerido): Selector CSS del campo
• value (string, requerido): Texto a introducir

Ejemplo:

{
  "selector": "input[name='email']",
  "value": "user@example.com"
}

puppeteer_screenshot

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

Parámetros:

• name (string, requerido): Nombre del archivo (sin extensión)
• selector (string, opcional): Selector CSS para capturar solo un elemento
• width (number, opcional): Ancho del viewport (default: 800)
• height (number, opcional): Alto del viewport (default: 600)

Ejemplo:

{
  "name": "homepage",
  "width": 1920,
  "height": 1080
}

puppeteer_evaluate

Ejecuta código JavaScript en el contexto del navegador.

Parámetros:

• script (string, requerido): Código JavaScript a ejecutar

Ejemplo:

{
  "script": "document.title"
}

puppeteer_hover

Pasa el cursor sobre un elemento.

Parámetros:

• selector (string, requerido): Selector CSS del elemento

Ejemplo:

{
  "selector": ".menu-item"
}

puppeteer_select

Selecciona una opción de un elemento select/dropdown.

Parámetros:

• selector (string, requerido): Selector CSS del elemento select
• value (string, requerido): Valor a seleccionar

Ejemplo:

{
  "selector": "select#country",
  "value": "ES"
}

## Desarrollo

```bash
# Modo watch (recompila automáticamente)
npm run watch

# Compilar
npm run build

Configuración para Servidores

Este servidor está configurado para ejecutarse en modo headless por defecto, lo que significa que:

• ✅ No requiere servidor X11 o entorno gráfico
• ✅ Funciona en contenedores Docker
• ✅ Compatible con servidores Linux sin GUI
• ✅ Optimizado para uso en VPS/Cloud
• ✅ Menor consumo de recursos

Flags de optimización incluidos:

--no-sandbox                    // Necesario en entornos Docker
--disable-setuid-sandbox        // Mejora compatibilidad
--disable-dev-shm-usage         // Evita problemas de memoria en contenedores
--disable-gpu                   // No requiere aceleración gráfica
--disable-software-rasterizer   // Reduce uso de CPU

Uso en Docker

Si ejecutas este servidor en Docker, asegúrate de instalar las dependencias necesarias:

FROM node:20-slim

# Instalar dependencias de Chromium
RUN apt-get update && apt-get install -y \
    chromium \
    chromium-sandbox \
    fonts-liberation \
    libasound2 \
    libatk-bridge2.0-0 \
    libatk1.0-0 \
    libatspi2.0-0 \
    libcups2 \
    libdbus-1-3 \
    libdrm2 \
    libgbm1 \
    libgtk-3-0 \
    libnspr4 \
    libnss3 \
    libwayland-client0 \
    libxcomposite1 \
    libxdamage1 \
    libxfixes3 \
    libxkbcommon0 \
    libxrandr2 \
    xdg-utils \
    && rm -rf /var/lib/apt/lists/*

# Configurar Puppeteer para usar Chromium instalado
ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true \
    PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium

WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

CMD ["node", "build/index.js"]

Seguridad

• El servidor tiene acceso completo al navegador y puede ejecutar JavaScript arbitrario
• Solo úsalo con fuentes de confianza
• Ten cuidado al ejecutar código JavaScript desde entradas no confiables
• En producción, considera remover el flag --disable-web-security del código fuente

Ventajas del Modo Headless

1. Sin dependencias gráficas: No requiere X11, Xvfb o servidor gráfico
2. Menor consumo de recursos: ~60% menos uso de memoria comparado con modo gráfico
3. Más rápido: Las operaciones son 10-20% más rápidas sin renderizado gráfico
4. Compatible con CI/CD: Funciona en pipelines de integración continua
5. Escalable: Fácil de replicar en múltiples contenedores
6. Más estable: Menos propensoa fallos relacionados con el sistema gráfico

Casos de Uso

• Web scraping automatizado
• Testing de aplicaciones web
• Generación de PDFs y screenshots
• Automatización de tareas en navegadores
• Integración con sistemas de IA para navegación web
• Monitoreo y validación de sitios web

Licencia

MIT

Contribuciones

Las contribuciones son bienvenidas. Por favor, abre un issue o pull request en el repositorio.