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.

Related MCP server: Puppeteer MCP Server

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

1. Clona este repositorio o descarga el código fuente

2. Instalar dependencias:

npm install

3. Construir el proyecto:

npm run build

4. 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:

1. Cierre por completo cualquier instancia de Chrome existente

2. 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

3. Navega a la página web deseada en Chrome

4. 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.