mcp-browser-automation-server

EmilianoAlmasia/mcp-browser-automation-server

3.1

If you are the rightful owner of mcp-browser-automation-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

MCP Browser Automation Server is a web automation server using Puppeteer, enabling LLMs to control browsers remotely via a simple REST API.

🎮 MCP Browser Automation Server

🌟 Descripción

Un servidor de automatización web basado en Puppeteer que permite a cualquier LLM controlar navegadores de forma remota a través de una API REST simple. Desarrollado durante experimentos con Model Context Protocol (MCP) para automatización de escritorios remotos y tareas web.

✨ Características Principales

  • 🌐 Control completo del navegador via API REST
  • 📸 Screenshots automáticos con análisis de contenido
  • 🎯 Sistema de clicks inteligente (texto y coordenadas)
  • ⌨️ Entrada de texto y teclas con encoding automático
  • 🕵️ Modo stealth para evitar detección de bots
  • 🧠 Memoria de workflow con checkpoints
  • ⏱️ Timeouts inteligentes y recuperación automática
  • 🎨 Screenshots del sistema completo (Windows PowerShell)

🚀 Instalación Rápida

1. Prerrequisitos

# Node.js 16+ requerido
node --version
npm --version

2. Instalar dependencias

npm install puppeteer puppeteer-extra puppeteer-extra-plugin-stealth express cors

3. Ejecutar servidor

node browser-server-enhanced-v2.js

4. ¡Listo!

Servidor ejecutándose en: http://localhost:3002

📚 API Reference

🚀 Lanzar navegador

curl "http://localhost:3002/launch?url=https://google.com"

📸 Capturar screenshot

curl "http://localhost:3002/screenshot?description=mi-screenshot"

🎯 Hacer clic por coordenadas

curl "http://localhost:3002/clickCoordinates?x=400&y=300"

👆 Hacer clic por texto

curl "http://localhost:3002/clickText?text=Buscar"

⌨️ Escribir texto

curl "http://localhost:3002/type?text=Hola%20mundo"

🔑 Presionar teclas

curl "http://localhost:3002/pressKey?key=Enter"

🤖 Uso con LLMs

Claude Code (MCP)

# Ejemplo de flujo completo para buscar en Google
curl -s "http://localhost:3002/launch?url=https://google.com"
curl -s "http://localhost:3002/clickCoordinates?x=384&y=300"
curl -s "http://localhost:3002/type?text=inteligencia%20artificial"
curl -s "http://localhost:3002/pressKey?key=Enter"
curl -s "http://localhost:3002/screenshot?description=resultados-busqueda"

Cualquier LLM

El LLM puede usar comandos curl simples para:

  1. Lanzar páginas web
  2. Interactuar con elementos (clicks, texto)
  3. Capturar screenshots con análisis
  4. Navegar paso a paso

📁 Estructura del Proyecto

📂 Proyecto MESSH/
├── 📄 browser-server-enhanced-v2.js    # Servidor principal
├── 📄 take-screenshot.ps1              # Screenshots sistema (Windows)
├── 📄 README.md                        # Esta documentación
├── 📄 package.json                     # Dependencias npm
├── 📄 EXAMPLES.md                      # Ejemplos de uso
└── 📂 screenshots/                     # Capturas guardadas
    ├── enhanced-v2-*.png
    └── screenshot-sistema-completo.png

🎯 Casos de Uso

✅ Automatización Web

  • Búsquedas en Google
  • Llenado de formularios
  • Navegación de sitios web
  • Scraping de datos

✅ Testing Automatizado

  • Pruebas de UI
  • Validación de flujos
  • Capturas de regresión

✅ Control Remoto

  • Escritorios remotos (MeshCentral)
  • VMs online (JSLinux, DistroSea)
  • Aplicaciones web

🔧 Configuración Avanzada

Modo Stealth (Anti-bot)

// Ya incluido en browser-server-enhanced-v2.js
const StealthPlugin = require('puppeteer-extra-plugin-stealth')
puppeteer.use(StealthPlugin())

Screenshots del Sistema (Windows)

# Ejecutar para capturas completas incluyendo iframes
powershell -ExecutionPolicy Bypass -File take-screenshot.ps1

🎓 Aprendizajes del Proyecto

🔍 Descubrimientos Técnicos

  • Puppeteer + iframes: Las capturas no muestran contenido de iframes
  • PowerShell screenshots: Capturan todo el sistema incluyendo iframes
  • MeshCentral remote: Funciona mejor con clicks por coordenadas
  • VMs limitadas: JSLinux/DistroSea tienen restricciones de conectividad

🏗️ Arquitectura MCP

  1. Ejecutar → Esperar → Screenshot → Analizar → Decidir
  2. Memoria de workflow con checkpoints para recovery
  3. API REST simple que cualquier LLM puede usar
  4. Timeouts inteligentes para elementos dinámicos

🚨 Limitaciones Conocidas

  • ⚠️ iframes: Puppeteer no captura contenido de iframes
  • ⚠️ VMs online: Conectividad limitada en emuladores
  • ⚠️ Detección de bots: Algunos sitios pueden bloquear
  • ⚠️ Windows only: PowerShell screenshots solo en Windows

🤝 Contribuir

  1. Fork el repositorio
  2. Crea una rama para tu feature
  3. Haz commit de tus cambios
  4. Push a la rama
  5. Abre un Pull Request

📄 Licencia

MIT License - Siéntete libre de usar, modificar y distribuir.

🙏 Créditos

Desarrollado durante experimentos con Claude Code y Model Context Protocol para automatización de browser y escritorios remotos. Ideal para integración con cualquier LLM que pueda ejecutar comandos HTTP.

💡 Tip: Este servidor funciona especialmente bien con LLMs que tienen acceso a herramientas de línea de comandos como curl o Bash.