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

Instalación

Opción 1: Instalar desde npm

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

Opción 2: Instalar desde la fuente

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

3. Construir el proyecto:

4. Ejecutar el servidor:

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:

Usando npx (sin instalación):

Si se instala desde la fuente:

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:

Usando npx (sin instalación):

Si se instala desde la fuente:

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.