Servidor MCP de Puppeteer

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

Reconocimiento

Este proyecto es una implementación experimental inspirada en @modelcontextprotocol/server-puppeteer . Si bien comparte objetivos y conceptos similares, explora enfoques alternativos para la automatización del navegador mediante el Protocolo de Contexto de Modelo.

Características

Navegar por páginas web
Tomar capturas de pantalla
Elementos de clic
Rellenar formularios
Seleccionar opciones
Elementos flotantes
Ejecutar JavaScript
Gestión inteligente de pestañas de Chrome:
- Conectarse a pestañas activas de Chrome
- Conservar las 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 la fuente

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

npm install

Construir el proyecto:

npm run build

Ejecutar el servidor:

npm start

Configuración del servidor MCP

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

Para la aplicación de escritorio de Claude

Agregue lo siguiente a su 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 a través de 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 la fuente:

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

Para la extensión VSCode de Claude

Agregue lo siguiente a su archivo de configuración MCP de la extensión 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 a través de 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 la fuente:

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

Para la instalación de origen, reemplace path/to/puppeteer-mcp-server con la ruta real donde instaló esta herramienta.

Uso

Modo estándar

El servidor lanzará una nueva instancia del navegador de forma predeterminada.

Modo de pestaña activa

Para conectarse a una ventana de Chrome existente:

Cierre por completo cualquier instancia de Chrome existente
Inicie 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
Conectarse usando la herramienta puppeteer_connect_active_tab :
{ "targetUrl": "https://example.com", // Optional: specific tab URL "debugPort": 9222 // Optional: defaults to 9222 }

El servidor hará lo siguiente:

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

Herramientas disponibles

pestaña activa de conexión de titiritero

Conéctese 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)

titiritero_navegar

Navegar a una URL.

Obligatorio: url : la URL a la que navegar

captura de pantalla del titiritero

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

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

clic del titiritero

Haga clic en un elemento de la página.

Obligatorio: selector - Selector CSS para el elemento en el que hacer clic

relleno de titiritero

Rellene un campo de entrada.

Requerido:
- selector - Selector CSS para campo de entrada
- value - Texto para ingresar

titiritero_seleccionar

Utilice menús desplegables.

Requerido:
- selector - Selector CSS para el elemento seleccionado
- value - Valor de la opción a seleccionar

titiritero_flotante

Pase el cursor sobre los elementos.

Obligatorio: selector - Selector CSS para el elemento sobre el que se pasa el cursor

titiritero_evaluar

Ejecute JavaScript en la consola del navegador.

Requerido: script - Código JavaScript a ejecutar

Consideraciones de seguridad

Al utilizar la depuración remota:

Habilitar solo en redes confiables
Utilice un puerto de depuración único
Cerrar el puerto de depuración cuando no esté en uso
Nunca exponga el puerto de depuración a redes públicas

Registro y depuración

Registro basado en archivos

El servidor implementa un registro completo utilizando Winston:

Ubicación: logs/ directorio
Patrón de archivo: mcp-puppeteer-YYYY-MM-DD.log
Rotación de registro:
- Rotación diaria
- Tamaño máximo: 20 MB 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
ADVERTENCIA: Mensajes de advertencia
ERROR: Eventos de error y excepciones

Información registrada

Eventos de inicio/apagado del servidor
Operaciones del navegador (iniciar, conectar, cerrar)
Intentos de navegación y resultados
Ejecuciones y resultados de herramientas
Detalles de errores con seguimientos de pila
Salida de la consola del navegador
Uso de recursos (capturas de pantalla, registros de la 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
Errores en la captura de pantalla

Cada llamada de herramienta devuelve:

Estado de éxito/fracaso
Mensaje de error detallado en caso de error
Datos del resultado de la operación en caso de éxito

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

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

Contribuyendo

¡Agradecemos sus contribuciones! Lea nuestras Pautas de Contribución para obtener más información sobre cómo enviar solicitudes de incorporación de cambios, informar problemas y contribuir al proyecto.

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.

You must be authenticated.

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

local-only server

The server can only run on the client's local machine because it depends on local resources.

Tools

Permite la automatización del navegador con Puppeteer, lo que admite la navegación, las interacciones de formularios y la conexión a instancias activas de Chrome para una interacción integral con la página web.

Related Resources

Reddit Discussion about this server

Related MCP Servers

Puppeteer MCP Server
jwaldor
A
security
F
license
A
quality
Enables LLMs to perform web browsing tasks, take screenshots, and execute JavaScript using Puppeteer for browser automation.
Last updated -
4
15,502
1
JavaScript
Steel Puppeteer
rdvo
-
security
A
license
-
quality
A Model Context Protocol server that enables LLMs to automate web browsers using Puppeteer, allowing navigation, screenshots, form filling, and JavaScript execution in a real browser environment.
Last updated -
JavaScript
MIT License
MCP Operator
willer
-
security
F
license
-
quality
A web browser automation server that allows AI assistants to control Chrome with persistent state management, enabling complex browsing tasks through asynchronous browser operations.
Last updated -
1
Python
Configurable Puppeteer MCP Server
afshawnlotfi
-
security
F
license
-
quality
A Model Context Protocol server that provides browser automation capabilities using Puppeteer with configurable options through environment variables, enabling LLMs to interact with web pages, take screenshots, and execute JavaScript in a browser environment.
Last updated -
1
JavaScript

View all related MCP servers