WaveXisMCP

Servidor MCP — 220 herramientas de automatización de navegador para LLMs

Chrome + Firefox · CDP + BiDi · 100% Python · cero Node.js · cero descarga de Chromium

---

Español | 简体中文 | 日本語

Servidor MCP que expone la biblioteca de automatización de navegador wavexis a los LLMs. 220 herramientas en 13 niveles de capacidad. Sin Node.js, sin descarga de Chromium: usa tu Chrome/Edge existente. 100% Python.

Demostración rápida

30 segundos para tu primera captura de pantalla. Añade esto a la configuración de tu cliente MCP (Claude Desktop, Cursor, Windsurf, VS Code):

{
  "mcpServers": {
    "wavexis": {
      "command": "uvx",
      "args": ["wavexis-mcp", "--caps", "all"]
    }
  }
}

Luego pregunta a tu LLM:

"Toma una captura de pantalla de página completa de https://example.com"

El LLM llama a wavexis_screenshot(url="https://example.com", full_page=true) y devuelve la captura de pantalla. Sin Node.js, sin descarga de Chromium, sin configuración más allá de lo anterior.

¿Por qué WaveXisMCP?

WaveXisMCP envuelve la biblioteca de automatización de navegador wavexis y la expone como un servidor MCP. No necesitas Node.js, Playwright ni una descarga separada de Chromium: WaveXisMCP lanza tu instalación existente de Chrome o Edge directamente.

Características clave

• 220 herramientas — 3 veces más que Playwright MCP (21), 2 veces más que zendriver-mcp (96)
• 13 niveles de capacidad — habilita solo lo que necesitas mediante --caps. Comienza con core (72 herramientas), añade niveles según sea necesario
• Chrome + Firefox — CDP para Chrome/Edge, BiDi para Firefox. Ambos lanzan automáticamente sus controladores desde PATH
• Sin descarga de Chromium — usa tu navegador existente. Instalación de ~5MB frente a ~400MB de Playwright MCP
• Modo sigiloso — stealth=true oculta navigator.webdriver, falsifica plugins/idiomas/entorno de ejecución de Chrome
• Errores estructurados — cada error incluye un campo suggestion para que el LLM se autocorrija sin ayuda humana
• YAML de múltiples acciones — encadena navegar → hacer clic → rellenar → captura de pantalla en una sola llamada de herramienta
• Acceso CDP/BiDi sin procesar — vía de escape para cualquier función del navegador no cubierta por una herramienta dedicada
• Auditorías Lighthouse, WebAuthn, Bluetooth, Cast — funciones especializadas que ningún otro servidor MCP cubre
• Protección SSRF, sandboxing de rutas, limitación de velocidad — seguridad integrada desde el primer día
• 593 pruebas, cobertura del 90% aplicada, E2E con Chrome real — listo para producción

Cómo funciona

You (natural language)
  → LLM decides which tool to call
    → WaveXisMCP receives the tool call
      → wavexis library executes it via CDP or BiDi
        → Chrome/Edge/Firefox performs the action
      ← Result returned as JSON (text, base64, file path)
    ← JSON passed back to LLM
  ← LLM summarizes the result for you

El LLM nunca ve el navegador directamente. Solo ve definiciones de herramientas (nombre, descripción, parámetros) y respuestas JSON. Esto significa que cualquier cliente LLM compatible con MCP funciona de inmediato: no se necesitan integraciones personalizadas.

Conceptos principales

• Herramienta — Una operación única del navegador (captura de pantalla, eval, clic, etc.) expuesta como herramienta MCP que cualquier cliente LLM puede llamar.
• Sesión — Una instancia persistente del navegador. Abre una sesión, encadena múltiples llamadas de herramientas, cierra cuando termines. Evita la sobrecarga de lanzar un navegador por acción.
• Modo sin estado — Llama a cualquier herramienta con un parámetro url. El navegador se lanza, ejecuta y cierra automáticamente.
• Niveles de capacidad — 13 niveles desde core (72 herramientas) hasta all (220 herramientas). Habilita solo lo que necesitas mediante --caps.
• Doble backend — CDP (nativo de Chromium, mediante cdpwave) y BiDi (multinavegador W3C, mediante bidiwave) con selección por sesión.
• Errores estructurados — Cada error incluye un campo suggestion que indica al LLM qué hacer a continuación, permitiendo la autocorrección sin intervención humana.

Instalación

pip install wavexis-mcp

Con backend CDP (Chromium):

pip install "wavexis-mcp[cdp]"

O ejecuta sin instalar (recomendado):

uvx wavexis-mcp

Requisitos

• Python: 3.11, 3.12 o 3.13
• Navegador: Google Chrome, Microsoft Edge o cualquier navegador basado en Chromium/Chrome
• Backend BiDi (opcional): ChromeDriver/EdgeDriver para Chrome, o geckodriver para Firefox

Inicio rápido

Añade a la configuración de tu cliente MCP (Claude Desktop, Cursor, Windsurf, VS Code):

{
  "mcpServers": {
    "wavexis": {
      "command": "uvx",
      "args": ["wavexis-mcp", "--caps", "all"]
    }
  }
}

O con pip:

{
  "mcpServers": {
    "wavexis": {
      "command": "wavexis-mcp",
      "args": ["--caps", "all"]
    }
  }
}

Modo sin estado (de un solo uso)

Llama a cualquier herramienta con un parámetro url: el navegador se lanza, ejecuta y cierra automáticamente:

wavexis_screenshot(url="https://example.com", full_page=true)

Modo de sesión (multipaso)

Abre una sesión, encadena múltiples acciones, cierra cuando termines:

wavexis_session_open(backend="cdp", headless=false)
→ {"session_id": "abc-123"}

wavexis_navigate(session_id="abc-123", url="https://example.com")
wavexis_click(session_id="abc-123", selector="#login")
wavexis_screenshot(session_id="abc-123")
wavexis_session_close(session_id="abc-123")

Interacción en lenguaje natural (M1)

Usa wavexis_act para interactuar con páginas usando lenguaje natural:

wavexis_session_open(backend="cdp")
wavexis_navigate(session_id="abc-123", url="https://example.com")
wavexis_act(session_id="abc-123", instruction="click the login button")
→ {"action": "click", "element": {"ref": "el-3", "role": "button", "name": "Login"}, "status": "ok"}

La herramienta wavexis_act toma una instantánea de accesibilidad, compara la instrucción con un elemento mediante puntuación de palabras clave y ejecuta la acción detectada (clic, escribir, rellenar, pasar el cursor). Sin llamadas LLM externas: coincidencia puramente heurística.

Niveles de capacidad

Nivel	Indicador	Herramientas	Características clave
Núcleo	siempre activo	72	Sesión, navegación, captura de pantalla, PDF, extracción, eval, DOM, entrada, cookies, pestañas, interacción NL, iframe, shadow DOM, eventos
Red	--caps=network	20	Cabeceras, UA, bloqueo, limitación, caché, HAR, interceptación, simulación, modificar req/resp, cuerpo de solicitud, reproducir HAR, lista de solicitudes
Almacenamiento	--caps=storage	18	localStorage, sessionStorage, almacenamiento de caché, IndexedDB, guardar/restaurar estado
Emulación	--caps=emulation	9	Dispositivo, viewport, geolocalización, zona horaria, modo oscuro, locale, CPU, táctil, sensores
Accesibilidad	--caps=a11y	4	Instantánea del árbol de accesibilidad, recorrido de nodos, auditoría axe-core
Interacciones	--caps=interactions	5	Diálogos, descargas, permisos
Herramientas de desarrollo	--caps=devtools	31	Rendimiento, CSS, depuración, superposición, consola, seguridad, gestión de ventanas, traza combinada, captura anotada
Visión	--caps=vision	7	Ratón basado en coordenadas (precisión de píxel)
Vídeo	--caps=video	4	Grabación de vídeo, capítulos, superposición de acciones
Pruebas	--caps=testing	6	Aserciones, generación de localizadores
Flujos de trabajo	--caps=workflows	6	YAML de múltiples acciones, CDP/BiDi sin procesar, CRUD de contexto de navegador
Datos	--caps=data	7	Generación de código, auditoría Lighthouse, extracción, interceptación de websocket, rastreo, diff visual, métricas web esenciales
Experimental	--caps=experimental	31	Service workers, animaciones, WebAuthn, WebAudio, medios, cast, bluetooth, extensiones, preferencias
Total	--caps=all	220

Predeterminado: --caps=core (72 herramientas). Habilitar todo: --caps=all. Habilitar específicos: --caps=network,storage,emulation.

Consejo: Comienza con --caps core y añade niveles según sea necesario. Cada nivel añade definiciones de herramientas al contexto del LLM, lo que consume tokens. Para la mayoría de las tareas, core,network,storage (110 herramientas) es un buen equilibrio.

Backends

WaveXisMCP admite dos backends con paridad total de funciones:

• CDP (cdpwave) — predeterminado, Protocolo de Chrome DevTools. WebSocket directo a Chrome/Edge. Sin controlador necesario. 57 dominios CDP. pip install "wavexis-mcp[cdp]"
• BiDi (bidiwave) — protocolo WebDriver BiDi, multinavegador W3C (Firefox, Chrome). Necesita chromedriver (Chrome) o geckodriver (Firefox); ambos se lanzan automáticamente desde PATH si no están en ejecución. pip install "wavexis-mcp[bidi]"

Selecciona por sesión:

# CDP (default, Chrome/Edge only)
wavexis_session_open(backend="cdp")

# BiDi with Chrome (auto-launches chromedriver)
wavexis_session_open(backend="bidi", browser="chrome")

# BiDi with Firefox (auto-launches geckodriver)
wavexis_session_open(backend="bidi", browser="firefox")

Conectar a Chrome existente

Usa connect_existing=True para lanzar Chrome con --remote-debugging-port y conectar a él. Útil para reutilizar un perfil de navegador con sesiones iniciadas:

# Launch Chrome with debug port and connect via CDP
wavexis_session_open(connect_existing=true)

# Reuse an existing Chrome profile (keeps logins, cookies, extensions)
wavexis_session_open(connect_existing=true, user_data_dir="C:/Users/me/ChromeProfile")

Chrome se lanza con ventana (headless se ignora). El subproceso del navegador se termina cuando se cierra la sesión.

YAML de múltiples acciones

Encadena múltiples acciones en una sola llamada de herramienta pasando una cadena YAML:

wavexis_multi_action(
    config="""
actions:
  - navigate: https://example.com
  - screenshot:
      full_page: true
  - eval: document.title
  - click: "#login"
  - type:
      selector: "#username"
      text: admin@example.com
  - screenshot: {}
""",
    session_id="abc-123"
)

Tipos de acción admitidos: navigate, screenshot, eval, click, type, fill. Establece continue_on_error: true para seguir ejecutando en caso de fallos.

Recursos y prompts MCP (M3)

Recursos (estado de navegador de solo lectura):

• wavexis://session/{id}/url — URL de la página actual
• wavexis://session/{id}/cookies — cookies como JSON
• wavexis://session/{id}/console — mensajes de consola
• wavexis://session/{id}/tabs — pestañas abiertas

Prompts (plantillas de flujo de trabajo):

• scrape_page(url, selector) — extraer y extraer contenido
• audit_page(url) — auditoría completa de accesibilidad + rendimiento
• fill_form(url, fields) — rellenar un formulario en una página
• debug_page(url) — depurar consola, red, rendimiento

Transporte HTTP

Ejecuta WaveXisMCP como servidor HTTP para CI/CD, instancias compartidas o Docker:

# HTTP on localhost
wavexis-mcp --transport http --port 8765

# HTTP with all tiers
wavexis-mcp --transport http --port 8765 --caps all

# HTTP with remote access (use behind a reverse proxy!)
wavexis-mcp --transport http --allow-remote --port 8765

Se vincula a 127.0.0.1 de forma predeterminada. Usa --allow-remote para 0.0.0.0.

Limitación de velocidad (M4)

Limitación de velocidad por sesión con cubo de tokens:

# 10 calls/sec, burst of 5
wavexis-mcp --rate-limit 10 --rate-burst 5

Cuando se supera, devuelve {"error": "rate_limited", "retry_after_ms": N}.

Docker

# Pull and run
docker run -p 8765:8765 ghcr.io/mathiaspaulenko/wavexis-mcp

# Or build locally
docker build -t wavexis-mcp .
docker run -p 8765:8765 wavexis-mcp

# Docker Compose
docker-compose up

Consulta la documentación de Docker para más detalles.

Comparación

Característica	Playwright MCP	WaveXisMCP
Lenguaje	TypeScript	Python
Node.js requerido	✗	✓ (sin Node.js)
Descarga Chromium (~200MB)	✓	✗ (usa navegador existente)
Tamaño de instalación	~400MB	~5MB
Inicio en frío	3.2s	0.8s
Herramientas totales	~21	220
Niveles de capacidad (opt-in)	✗	✓ (13 niveles)
Protocolo dual (CDP + BiDi)	✗	✓
Soporte Firefox	✓ (básico)	✓ (BiDi + auto-lanzamiento de geckodriver)
Selección de backend (por sesión)	✗	✓
Modo sigiloso / anti-bot	✗	✓
Acceso CDP/BiDi sin procesar	✗	✓ (vía de escape)
Procesamiento por lotes YAML de múltiples acciones	✗	✓
Grabación de vídeo	✗	✓
Auditoría Lighthouse	✗	✓
WebAuthn / Bluetooth / Cast	✗	✓
Interacción en lenguaje natural	✗	✓ (wavexis_act)
Recursos y prompts MCP	✗	✓
Limitación de velocidad	✗	✓
Protección SSRF	✗	✓
Errores estructurados con sugerencias	✗	✓

Nota: Playwright MCP admite WebKit (Safari) — WaveXisMCP no (todavía). Consulta la hoja de ruta para las funciones planificadas.

Documentación

Documentación completa, referencia de API y ejemplos están alojados en mathiaspaulenko.github.io/wavexis-mcp.

Secciones clave:

• Inicio rápido
• Arquitectura
• Configuración
• Docker
• Transporte HTTP
• Limitación de velocidad
• Referencia de herramientas
• Ejemplos

Manejo de errores

Todas las herramientas devuelven JSON de error estructurado en caso de fallo. Cada error incluye un campo suggestion que guía al LLM hacia la siguiente acción:

{
  "error": "Session 'abc-123' not found.",
  "tool": "wavexis_navigate",
  "type": "SessionNotFoundError",
  "message": "Session 'abc-123' not found.",
  "suggestion": "Call wavexis_session_open first to create a browser session."
}

Esto permite que el LLM se autocorrija sin intervención humana: lee la sugerencia y llama a la herramienta recomendada.

Arquitectura

WaveXisMCP se sitúa en la cima de un ecosistema de tres capas:

WaveXisMCP (MCP server, 220 tools)
└─ wraps → wavexis (browser automation library)
               ├─ cdpwave (CDP backend, Chromium-native)
               └─ bidiwave (BiDi backend, W3C cross-browser)

• cdpwave — biblioteca Python asíncrona de bajo nivel para el Protocolo de Chrome DevTools. WebSocket directo a Chrome/Edge. Sin binario de controlador necesario.
• bidiwave — biblioteca Python asíncrona de bajo nivel para el protocolo WebDriver BiDi (estándar W3C). Funciona con Firefox, Chrome y Edge.
• wavexis — biblioteca de automatización de navegador de alto nivel que abstrae cdpwave y bidiwave detrás de una interfaz unificada AbstractBackend.
• WaveXisMCP — servidor MCP que envuelve wavexis. Expone cada método de backend como herramienta MCP con validación de entrada Pydantic v2, respuestas JSON y filtrado por nivel de capacidad.

Consulta la documentación de Arquitectura para el diseño completo del sistema, diagramas de flujo de datos y ADRs.

Desarrollo

git clone https://github.com/MathiasPaulenko/wavexis-mcp.git
cd wavexis-mcp
pip install -e ".[dev]"

# Run quality checks
ruff check wavexis_mcp tests
ruff format --check
mypy wavexis_mcp
python -m bandit -r wavexis_mcp

# Run tests
pytest tests/unit -v

Contribuciones

Las contribuciones son bienvenidas. Consulta CONTRIBUTING.md para el flujo de trabajo de desarrollo, estándares de codificación y proceso de solicitudes de extracción. Para problemas de seguridad, consulta SECURITY.md.

Agradecimientos

WaveXisMCP está construido sobre la biblioteca de automatización de navegador wavexis y el Protocolo de Contexto de Modelo. Gracias a las comunidades de código abierto de Python y MCP por las herramientas y estándares que hacen posible este proyecto.

Licencia

MIT

mcp-name: io.github.MathiasPaulenko/wavexis-mcp