Servidor MCP Selenium WebDriver

Un servidor MCP (Model Context Protocol) completo que implementa Selenium WebDriver para automatización de navegadores con capacidades avanzadas de evasión de detección, soporte para múltiples navegadores y funcionalidades completas de interacción web.

Características Principales

🚀 Automatización Completa de Navegadores

• Navegación web: Navegar a URLs, obtener información de páginas
• Interacción con elementos: Buscar, hacer clic, escribir texto, subir archivos
• Acciones de ratón: Hover, drag and drop, clic derecho, doble clic
• Manejo de teclado: Envío de teclas especiales (Enter, Tab, flechas, etc.)
• Capturas de pantalla: Pantalla completa o elementos específicos
• Ejecución de JavaScript: Scripts personalizados en el navegador

🕵️ Evasión de Detección Avanzada

• Undetected Chrome: Integración con undetected-chromedriver
• Randomización: User agents y viewports aleatorios
• Scripts stealth: Ocultación de propiedades de automatización
• Simulación humana: Escritura y scroll con delays realistas
• Gestión de cookies: Control completo de cookies y sesiones

🌐 Soporte Multi-Navegador

• Chrome: Soporte completo con evasión de detección
• Firefox: Implementación nativa de Selenium
• Detección automática: Identificación de navegadores instalados
• Configuraciones específicas: Optimizaciones por navegador

⚙️ Gestión Avanzada de Sesiones

• Múltiples sesiones: Hasta 10 sesiones simultáneas por defecto
• Gestión automática: Limpieza de sesiones expiradas
• Configuraciones flexibles: Presets para diferentes casos de uso
• Proxies: Soporte para HTTP, HTTPS y SOCKS

Instalación

Requisitos Previos

• Python 3.8 o superior
• Chrome y/o Firefox instalados
• Dependencias del sistema para Selenium

Instalación de Dependencias

# Clonar o descargar el proyecto
cd mcp_selenium_server

# Instalar dependencias de Python
pip install -r requirements.txt

Dependencias del Sistema

Ubuntu/Debian

# Chrome
wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo apt-key add -
echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" | sudo tee /etc/apt/sources.list.d/google-chrome.list
sudo apt update
sudo apt install google-chrome-stable

# Firefox
sudo apt install firefox

CentOS/RHEL

# Chrome
sudo yum install -y google-chrome-stable

# Firefox
sudo yum install firefox

Windows

• Descargar e instalar Chrome desde https://www.google.com/chrome/
• Descargar e instalar Firefox desde https://www.mozilla.org/firefox/

macOS

# Con Homebrew
brew install --cask google-chrome
brew install --cask firefox

Configuración

Configuraciones Predefinidas

El servidor incluye tres configuraciones predefinidas:

1. Configuración por Defecto

DEFAULT_CONFIG = ServerConfig(
    max_sessions=10,
    session_timeout=3600,
    default_browser="chrome",
    browser_options=BrowserOptions(
        headless=False,
        window_width=1920,
        window_height=1080,
        incognito=True
    )
)

2. Configuración Stealth (Recomendada para evasión)

STEALTH_CONFIG = ServerConfig(
    browser_options=BrowserOptions(
        headless=True,
        user_agent="Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36...",
        disable_images=True,
        custom_args=[
            "--disable-blink-features=AutomationControlled",
            "--disable-dev-shm-usage",
            "--no-first-run",
            # ... más argumentos stealth
        ]
    ),
    detection_evasion=DetectionEvasionConfig(
        use_undetected_chrome=True,
        stealth_mode=True,
        randomize_user_agent=True,
        randomize_viewport=True
    )
)

3. Configuración de Rendimiento

PERFORMANCE_CONFIG = ServerConfig(
    browser_options=BrowserOptions(
        headless=True,
        disable_images=True,
        disable_javascript=False,
        custom_args=[
            "--disable-dev-shm-usage",
            "--disable-gpu",
            "--no-sandbox"
        ]
    )
)

Configuración de Proxies

proxy_config = {
    "http": "http://proxy.example.com:8080",
    "https": "https://proxy.example.com:8080",
    "socks": "socks5://proxy.example.com:1080"
}

Uso Básico

Iniciar el Servidor

# Modo desarrollo
python server.py

# Con MCP CLI
mcp dev server.py

# Instalar en Claude Desktop
mcp install server.py

Ejemplo de Uso Básico

# 1. Iniciar navegador
result = start_browser(
    browser_type="chrome",
    options={
        "headless": False,
        "window_width": 1920,
        "window_height": 1080
    },
    detection_evasion={
        "use_undetected_chrome": True,
        "stealth_mode": True
    }
)
session_id = result["session_id"]

# 2. Navegar a una página
navigate_to_url(session_id, "https://example.com")

# 3. Buscar un elemento
element = find_element(
    session_id=session_id,
    strategy="css_selector",
    value="input[name='search']"
)

# 4. Escribir texto
type_text(
    session_id=session_id,
    strategy="css_selector",
    value="input[name='search']",
    text="selenium automation"
)

# 5. Hacer clic en botón
click_element(
    session_id=session_id,
    strategy="css_selector",
    value="button[type='submit']"
)

# 6. Tomar captura de pantalla
take_screenshot(
    session_id=session_id,
    file_path="/path/to/screenshot.png"
)

# 7. Cerrar navegador
close_browser(session_id)

Herramientas MCP Disponibles

Gestión de Navegadores

Navegación y Páginas

Interacción con Elementos

Acciones Avanzadas

Evasión de Detección

Gestión de Sesiones

Gestión de Cookies

Configuración del Servidor

Ejemplos Avanzados

Automatización con Evasión de Detección

# Configuración stealth completa
session_result = start_browser(
    browser_type="chrome",
    options={
        "headless": True,
        "disable_images": True,
        "incognito": True
    },
    detection_evasion={
        "use_undetected_chrome": True,
        "stealth_mode": True,
        "randomize_user_agent": True,
        "randomize_viewport": True
    }
)
session_id = session_result["session_id"]

# Aplicar modo stealth adicional
apply_stealth_mode(session_id)

# Navegar con delays humanos
navigate_to_url(session_id, "https://example.com")
add_random_delay(1.0, 3.0)

# Scroll humano
scroll_like_human(session_id, "down", 500, 8)
add_random_delay(0.5, 1.5)

# Escritura humana
simulate_human_typing(
    session_id=session_id,
    strategy="id",
    value="search-input",
    text="automated search query",
    min_delay=0.05,
    max_delay=0.15
)

# Gestión de cookies
manage_cookies(
    session_id=session_id,
    action="add",
    cookie_data={
        "name": "session_token",
        "value": "abc123",
        "domain": "example.com"
    }
)

Automatización de Formularios

# Llenar formulario complejo
session_id = start_browser("chrome")["session_id"]
navigate_to_url(session_id, "https://forms.example.com")

# Campos de texto
type_text(session_id, "id", "first_name", "John")
type_text(session_id, "id", "last_name", "Doe")
type_text(session_id, "id", "email", "john.doe@example.com")

# Seleccionar dropdown
click_element(session_id, "id", "country_select")
click_element(session_id, "xpath", "//option[text()='United States']")

# Subir archivo
upload_file(
    session_id=session_id,
    strategy="id",
    value="file_upload",
    file_path="/path/to/document.pdf"
)

# Checkbox
click_element(session_id, "id", "terms_checkbox")

# Enviar formulario
click_element(session_id, "css_selector", "button[type='submit']")

# Esperar y verificar
add_random_delay(2.0, 4.0)
page_info = get_page_info(session_id)
print(f"Página actual: {page_info['title']}")

Scraping con Múltiples Sesiones

# Iniciar múltiples sesiones
sessions = []
urls = ["https://site1.com", "https://site2.com", "https://site3.com"]

for i, url in enumerate(urls):
    result = start_browser(
        browser_type="chrome",
        options={"headless": True},
        detection_evasion={"use_undetected_chrome": True}
    )
    session_id = result["session_id"]
    sessions.append(session_id)
    
    # Navegar en paralelo
    navigate_to_url(session_id, url)
    apply_stealth_mode(session_id)

# Procesar cada sesión
for i, session_id in enumerate(sessions):
    # Extraer datos
    elements = find_element(
        session_id=session_id,
        strategy="css_selector",
        value=".data-item",
        multiple=True
    )
    
    # Tomar captura
    take_screenshot(
        session_id=session_id,
        file_path=f"/screenshots/site_{i+1}.png"
    )

# Limpiar todas las sesiones
close_all_sessions()

Estrategias de Localización de Elementos

El servidor soporta todas las estrategias estándar de Selenium:

Ejemplos de Selectores

# Por ID
find_element(session_id, "id", "submit-btn")

# Por clase CSS
find_element(session_id, "class_name", "form-control")

# Selector CSS complejo
find_element(session_id, "css_selector", "div.modal .btn-primary:not(:disabled)")

# XPath avanzado
find_element(session_id, "xpath", "//table//tr[contains(@class, 'data-row')][position()>1]")

# Múltiples elementos
find_element(session_id, "css_selector", ".product-item", multiple=True)

Configuración de Proxies

Tipos de Proxy Soportados

# HTTP Proxy
proxy_config = {"http": "http://proxy.example.com:8080"}

# HTTPS Proxy
proxy_config = {"https": "https://proxy.example.com:8080"}

# SOCKS Proxy
proxy_config = {"socks": "socks5://proxy.example.com:1080"}

# Proxy con autenticación
proxy_config = {"http": "http://user:pass@proxy.example.com:8080"}

# Usar proxy al iniciar navegador
start_browser(
    browser_type="chrome",
    proxy=proxy_config,
    options={"headless": True}
)

Manejo de Errores

El servidor maneja automáticamente los errores comunes y proporciona mensajes descriptivos:

# Ejemplo de respuesta con error
{
    "success": False,
    "error": "Timeout: Elemento no encontrado",
    "message": "No se pudo encontrar elemento con id='missing-element' en 10 segundos"
}

# Ejemplo de respuesta exitosa
{
    "success": True,
    "session_id": "abc123-def456",
    "message": "Navegador chrome iniciado exitosamente"
}

Errores Comunes y Soluciones

Mejores Prácticas

Para Evasión de Detección

1. Usar configuración stealth: Siempre aplicar STEALTH_CONFIG para sitios que detectan bots
2. Delays aleatorios: Agregar delays entre acciones para simular comportamiento humano
3. Randomización: Cambiar user agents y viewports regularmente
4. Gestión de cookies: Mantener cookies de sesión para parecer un usuario real
5. Scroll gradual: Usar scroll_like_human en lugar de scroll instantáneo

Para Rendimiento

1. Modo headless: Usar para operaciones en lote
2. Deshabilitar imágenes: Reducir tiempo de carga
3. Gestión de sesiones: Cerrar sesiones no utilizadas
4. Timeouts apropiados: Configurar timeouts según la velocidad del sitio

Para Estabilidad

1. Manejo de errores: Siempre verificar success en las respuestas
2. Limpieza de sesiones: Usar cleanup_expired_sessions regularmente
3. Verificar elementos: Usar find_element antes de interactuar
4. Capturas de pantalla: Tomar capturas para debugging

Limitaciones

• Máximo de sesiones: 10 sesiones simultáneas por defecto (configurable)
• Timeout de sesión: 1 hora por defecto (configurable)
• Navegadores soportados: Chrome y Firefox únicamente
• Detección: Algunos sitios avanzados pueden detectar automatización

Solución de Problemas

Problemas de Instalación

# Error: ChromeDriver no encontrado
pip install --upgrade webdriver-manager

# Error: Dependencias del sistema
sudo apt-get install -y libgconf-2-4 libxss1 libxtst6 libxrandr2 libasound2 libpangocairo-1.0-0 libatk1.0-0 libcairo-gobject2 libgtk-3-0 libgdk-pixbuf2.0-0

# Error: Permisos
sudo chmod +x /usr/bin/google-chrome

Problemas de Ejecución

# Verificar navegadores disponibles
python -c "
from browser_detection import BrowserDetection
bd = BrowserDetection()
print(bd.detect_available_browsers())
"

# Probar configuración básica
python -c "
from webdriver_manager import WebDriverManager
wm = WebDriverManager()
driver = wm.create_driver('chrome', BrowserOptions())
print('Chrome funciona correctamente')
driver.quit()
"

Contribución

Para contribuir al proyecto:

1. Fork el repositorio
2. Crear una rama para la nueva característica
3. Implementar cambios con tests
4. Enviar pull request

Licencia

Este proyecto está bajo la licencia MIT.