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
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
| Herramienta | Descripción |
|---|
start_browser | Inicia una nueva sesión de navegador |
close_browser | Cierra una sesión específica |
detect_available_browsers | Detecta navegadores instalados |
get_recommended_browser | Obtiene el navegador recomendado |
check_browser_support | Verifica soporte de WebDriver |
Navegación y Páginas
| Herramienta | Descripción |
|---|
navigate_to_url | Navega a una URL específica |
get_page_info | Obtiene información de la página actual |
execute_script | Ejecuta JavaScript en el navegador |
Interacción con Elementos
| Herramienta | Descripción |
|---|
find_element | Busca elementos con diferentes estrategias |
click_element | Hace clic en un elemento |
type_text | Escribe texto en un elemento |
upload_file | Sube archivos a inputs de tipo file |
Acciones Avanzadas
| Herramienta | Descripción |
|---|
perform_mouse_action | Acciones de ratón (hover, drag & drop) |
send_keys | Envía teclas especiales |
take_screenshot | Captura pantalla completa o elementos |
Evasión de Detección
| Herramienta | Descripción |
|---|
apply_stealth_mode | Aplica todas las técnicas stealth |
randomize_user_agent | Cambia a un user agent aleatorio |
randomize_viewport | Cambia el tamaño de ventana |
simulate_human_typing | Escritura con delays humanos |
scroll_like_human | Scroll gradual simulando humano |
add_random_delay | Agrega delays aleatorios |
Gestión de Sesiones
| Herramienta | Descripción |
|---|
list_active_sessions | Lista todas las sesiones activas |
get_session_info | Información detallada de una sesión |
close_all_sessions | Cierra todas las sesiones |
cleanup_expired_sessions | Limpia sesiones expiradas |
Gestión de Cookies
| Herramienta | Descripción |
|---|
manage_cookies | Gestión completa de cookies |
Configuración del Servidor
| Herramienta | Descripción |
|---|
get_server_status | Estado actual del servidor |
update_server_config | Actualiza configuración con presets |
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"
}
)
# 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:
| Estrategia | Descripción | Ejemplo |
|---|
id | Por atributo ID | "search-button" |
name | Por atributo name | "username" |
class_name | Por clase CSS | "btn-primary" |
tag_name | Por nombre de etiqueta | "button" |
css_selector | Selector CSS | "div.container > p" |
xpath | Expresión XPath | "//div[@class='content']//p" |
link_text | Texto exacto del enlace | "Click here" |
partial_link_text | Texto parcial del enlace | "Click" |
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
| Error | Causa | Solución |
|---|
Sesión no encontrada | ID de sesión inválido | Verificar que la sesión esté activa |
Timeout: Elemento no encontrado | Selector incorrecto o elemento no visible | Revisar selector y aumentar timeout |
WebDriverException | Problema con el driver | Reinstalar webdriver-manager |
ElementNotInteractableException | Elemento no clickeable | Usar scroll o esperar a que sea visible |
Mejores Prácticas
Para Evasión de Detección
- Usar configuración stealth: Siempre aplicar
STEALTH_CONFIG para sitios que detectan bots - Delays aleatorios: Agregar delays entre acciones para simular comportamiento humano
- Randomización: Cambiar user agents y viewports regularmente
- Gestión de cookies: Mantener cookies de sesión para parecer un usuario real
- Scroll gradual: Usar
scroll_like_human en lugar de scroll instantáneo
Para Rendimiento
- Modo headless: Usar para operaciones en lote
- Deshabilitar imágenes: Reducir tiempo de carga
- Gestión de sesiones: Cerrar sesiones no utilizadas
- Timeouts apropiados: Configurar timeouts según la velocidad del sitio
Para Estabilidad
- Manejo de errores: Siempre verificar
success en las respuestas - Limpieza de sesiones: Usar
cleanup_expired_sessions regularmente - Verificar elementos: Usar
find_element antes de interactuar - 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:
- Fork el repositorio
- Crear una rama para la nueva característica
- Implementar cambios con tests
- Enviar pull request
Licencia
Este proyecto está bajo la licencia MIT.