Puppeteer MCP

pptr-mcp

Servidor MCP para automatización de navegador mediante Puppeteer. A diferencia de otros MCP de navegador que exponen herramientas fijas (navegar, hacer clic, captura de pantalla), este servidor ejecuta código JavaScript arbitrario con acceso directo a la instancia del navegador Puppeteer.

Diferencia clave

La mayoría de los servidores MCP de navegador proporcionan un conjunto limitado de acciones predefinidas. Este enfoque requiere múltiples idas y vueltas para flujos de trabajo complejos y no puede manejar casos límite.

pptr-mcp adopta un enfoque diferente: expone una única herramienta execute que ejecuta tu código JavaScript en una VM de Node.js con un global browser. Escribes código Puppeteer directamente, obteniendo acceso completo a la API en una sola llamada.

Traditional MCP (5 round-trips)         pptr-mcp (1 round-trip)
================================        ================================

  Agent           Server                  Agent           Server
    |                |                      |                |
    |-- navigate --->|                      |-- execute ---->|
    |<-- ok ---------|                      |                |
    |                |                      |   +------------------------+
    |-- waitFor ---->|                      |   | const page = await     |
    |<-- ok ---------|                      |   |   browser.newPage();   |
    |                |                      |   | await page.goto(url);  |
    |-- click ------>|                      |   | await page.click(s);   |
    |<-- ok ---------|                      |   | await page.type(i, t); |
    |                |                      |   | return await           |
    |-- type ------->|                      |   |   page.screenshot();   |
    |<-- ok ---------|                      |   +------------------------+
    |                |                      |                |
    |-- screenshot ->|                      |<-- result -----|
    |<-- image ------|                      |                |
    |                |                      |                |

Requisitos

• Node.js >= 20

Instalación

npm install -g pptr-mcp

Configuración de MCP

Añade a la configuración de tu cliente MCP (por ejemplo, Claude Desktop):

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["pptr-mcp"]
    }
  }
}

Con opciones de CLI:

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["pptr-mcp", "--no-headless", "--viewport=1080p"]
    }
  }
}

Con banderas personalizadas de Chrome (después de --):

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": [
        "pptr-mcp",
        "--viewport=1280x720",
        "--",
        "--proxy-server=http://proxy:8080"
      ]
    }
  }
}

Opciones de CLI

Opción	Descripción
--no-headless	Ejecutar con ventana de navegador visible
--viewport=VALUE	Establecer tamaño de viewport (por ejemplo, 1920x1080 o 1080p)
--help, -h	Mostrar ayuda
-- [args]	Pasar argumentos restantes a Chrome

Las opciones desconocidas antes de -- también se pasan a Chrome.

Plugin de Claude Code

Instalar como plugin de Claude Code:

/plugin marketplace add iatsiuk/pptr-mcp
/plugin install pptr-mcp@pptr-mcp

Variables de entorno

Variable	Descripción
CHROME_PATH	Ruta al ejecutable de Chrome
PUPPETEER_EXECUTABLE_PATH	Alternativa a CHROME_PATH
PUPPETEER_CACHE_DIR	Directorio de caché de descarga del navegador
PPTR_MCP_TIMEOUT	Tiempo de espera de ejecución en ms (predeterminado: 30000)

Herramienta: execute

Ejecuta código JavaScript con acceso al navegador Puppeteer.

Parámetros

Nombre	Tipo	Predeterminado	Descripción
code	string	requerido	Código JavaScript a ejecutar
persistent	boolean	true	Reutilizar sesión de navegador entre llamadas

Recetas

Deshabilitar modo headless

Mostrar ventana del navegador durante la ejecución:

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["pptr-mcp", "--no-headless"]
    }
  }
}

Directorio de perfil personalizado de Chrome

Usa tu propio perfil de Chrome con inicios de sesión y cookies guardados:

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["pptr-mcp", "--", "--user-data-dir=/path/to/profile"]
    }
  }
}

Usar Chrome del sistema en lugar del descargado

Por defecto, pptr-mcp descarga Chrome for Testing, una versión optimizada y probada para el Puppeteer incluido. Para usar el Chrome de tu sistema en su lugar:

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["pptr-mcp"],
      "env": {
        "CHROME_PATH": "/path/to/chrome"
      }
    }
  }
}

Seguridad

Este servidor está diseñado para desarrollo local de confianza con asistentes LLM (Claude Code, Cursor, etc.). El código que se ejecuta proviene del LLM a petición tuya.

Qué significa esto

• No es un sandbox: La VM de Node.js aísla el código por conveniencia, no por seguridad. No está diseñada para ejecutar código no confiable.
• Control total del navegador: El código ejecutado puede navegar a cualquier URL, leer contenido de páginas, tomar capturas de pantalla e interactuar con aplicaciones web.
• Chrome se ejecuta sin sandbox: La bandera --no-sandbox se usa para compatibilidad con Docker/contenedores.
• Sesiones persistentes: Con persistent: true (predeterminado), las cookies y el estado del navegador se conservan entre llamadas. Usa persistent: false para aislamiento.

No diseñado para

• Implementaciones de servidor compartidas o multiinquilino
• Ejecutar código no confiable de fuentes externas
• Construir servicios web que acepten entrada arbitraria de usuarios

Licencia

WTFPL