WaveXisMCP

Servidor MCP — 220 ferramentas de automação de navegador para LLMs

Chrome + Firefox · CDP + BiDi · 100% Python · zero Node.js · zero download de Chromium

---

English | 简体中文 | 日本語

Servidor MCP que expõe a biblioteca de automação de navegador wavexis para LLMs. 220 ferramentas em 13 níveis de capacidade. Sem Node.js, sem download de Chromium — usa seu Chrome/Edge existente. 100% Python.

Demonstração rápida

30 segundos para sua primeira captura de tela. Adicione isto à configuração do seu cliente MCP (Claude Desktop, Cursor, Windsurf, VS Code):

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

Depois peça ao seu LLM:

"Tire uma captura de tela de página inteira de https://example.com"

O LLM chama wavexis_screenshot(url="https://example.com", full_page=true) e retorna a captura de tela. Sem Node.js, sem download de Chromium, sem configuração além do que está acima.

Por que WaveXisMCP?

O WaveXisMCP encapsula a biblioteca de automação de navegador wavexis e a expõe como um servidor MCP. Você não precisa de Node.js, Playwright ou download separado de Chromium — o WaveXisMCP inicia sua instalação existente do Chrome ou Edge diretamente.

Principais recursos

• 220 ferramentas — 3x mais que Playwright MCP (21), 2x mais que zendriver-mcp (96)
• 13 níveis de capacidade — ative apenas o que você precisa via --caps. Comece com core (72 ferramentas), adicione níveis conforme necessário
• Chrome + Firefox — CDP para Chrome/Edge, BiDi para Firefox. Ambos iniciam seus drivers automaticamente a partir do PATH
• Sem download de Chromium — usa seu navegador existente. Instalação de ~5MB vs ~400MB para Playwright MCP
• Modo stealth — stealth=true oculta navigator.webdriver, falsifica plugins/idiomas/runtime do Chrome
• Erros estruturados — todo erro inclui um campo suggestion para que o LLM se autocorrija sem ajuda humana
• YAML de múltiplas ações — encadeie navegar → clicar → preencher → capturar tela em uma única chamada de ferramenta
• Acesso bruto a CDP/BiDi — saída de emergência para qualquer recurso do navegador não coberto por uma ferramenta dedicada
• Auditorias Lighthouse, WebAuthn, Bluetooth, Cast — recursos de nicho que nenhum outro servidor MCP cobre
• Proteção SSRF, sandbox de caminhos, limite de taxa — segurança incorporada desde o primeiro dia
• 593 testes, 90% de cobertura garantida, E2E com Chrome real — pronto para produção

Como 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

O LLM nunca vê o navegador diretamente. Ele vê apenas definições de ferramentas (nome, descrição, parâmetros) e respostas JSON. Isso significa que qualquer cliente LLM compatível com MCP funciona imediatamente — sem integrações personalizadas.

Conceitos principais

• Ferramenta — Uma única operação de navegador (captura de tela, eval, clique, etc.) exposta como uma ferramenta MCP que qualquer cliente LLM pode chamar.
• Sessão — Uma instância persistente do navegador. Abra uma sessão, encadeie várias chamadas de ferramentas, feche quando terminar. Evita a sobrecarga de iniciar um navegador por ação.
• Modo sem estado — Chame qualquer ferramenta com um parâmetro url. O navegador inicia, executa e fecha automaticamente.
• Níveis de capacidade — 13 níveis de core (72 ferramentas) a all (220 ferramentas). Ative apenas o que você precisa via --caps.
• Backend duplo — CDP (nativo do Chromium, via cdpwave) e BiDi (W3C entre navegadores, via bidiwave) com seleção por sessão.
• Erros estruturados — Todo erro inclui um campo suggestion que diz ao LLM o que fazer em seguida, permitindo autocorreção sem intervenção humana.

Instalação

pip install wavexis-mcp

Com backend CDP (Chromium):

pip install "wavexis-mcp[cdp]"

Ou execute sem instalar (recomendado):

uvx wavexis-mcp

Requisitos

• Python: 3.11, 3.12 ou 3.13
• Navegador: Google Chrome, Microsoft Edge ou qualquer navegador baseado em Chromium/Chrome
• Backend BiDi (opcional): ChromeDriver/EdgeDriver para Chrome, ou geckodriver para Firefox

Início rápido

Adicione à configuração do seu cliente MCP (Claude Desktop, Cursor, Windsurf, VS Code):

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

Ou com pip:

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

Modo sem estado (uso único)

Chame qualquer ferramenta com um parâmetro url — o navegador inicia, executa e fecha automaticamente:

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

Modo de sessão (várias etapas)

Abra uma sessão, encadeie várias ações, feche quando terminar:

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")

Interação em linguagem natural (M1)

Use wavexis_act para interagir com páginas usando linguagem 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"}

A ferramenta wavexis_act tira um snapshot de a11y, combina a instrução com um elemento usando pontuação por palavras-chave e executa a ação detectada (clique, digitação, preenchimento, passar o mouse). Sem chamadas externas de LLM — correspondência puramente heurística.

Níveis de capacidade

Nível	Flag	Ferramentas	Principais recursos
Núcleo	sempre ativo	72	Sessão, navegação, captura de tela, PDF, extração, eval, DOM, entrada, cookies, abas, interação em linguagem natural, iframe, shadow DOM, eventos
Rede	--caps=network	20	Headers, UA, bloqueio, throttling, cache, HAR, interceptação, mock, modificar req/resp, corpo da requisição, replay de HAR, lista de requisições
Armazenamento	--caps=storage	18	localStorage, sessionStorage, armazenamento de cache, IndexedDB, salvar/restaurar estado
Emulação	--caps=emulation	9	Dispositivo, viewport, geolocalização, fuso horário, modo escuro, locale, CPU, toque, sensores
A11y	--caps=a11y	4	Snapshot da árvore de acessibilidade, travessia de nós, auditoria axe-core
Interações	--caps=interactions	5	Diálogos, downloads, permissões
DevTools	--caps=devtools	31	Performance, CSS, depuração, overlay, console, segurança, gerenciamento de janelas, trace combinado, captura de tela anotada
Visão	--caps=vision	7	Mouse baseado em coordenadas (precisão de pixel)
Vídeo	--caps=video	4	Gravação de vídeo, capítulos, overlay de ações
Testes	--caps=testing	6	Asserções, geração de localizadores
Fluxos de trabalho	--caps=workflows	6	YAML de múltiplas ações, CDP/BiDi bruto, CRUD de contexto do navegador
Dados	--caps=data	7	Codegen, auditoria Lighthouse, extração, interceptação de websocket, crawl, diff visual, core web vitals
Experimental	--caps=experimental	31	Service workers, animações, WebAuthn, WebAudio, mídia, cast, bluetooth, extensões, preferências
Total	--caps=all	220

Padrão: --caps=core (72 ferramentas). Ative todas: --caps=all. Ative específicas: --caps=network,storage,emulation.

Dica: Comece com --caps core e adicione níveis conforme necessário. Cada nível adiciona definições de ferramentas ao contexto do LLM, o que consome tokens. Para a maioria das tarefas, core,network,storage (110 ferramentas) é um bom equilíbrio.

Backends

O WaveXisMCP suporta dois backends com paridade total de recursos:

• CDP (cdpwave) — padrão, Chrome DevTools Protocol. WebSocket direto para Chrome/Edge. Sem necessidade de driver. 57 domínios CDP. pip install "wavexis-mcp[cdp]"
• BiDi (bidiwave) — protocolo WebDriver BiDi, W3C entre navegadores (Firefox, Chrome). Precisa de chromedriver (Chrome) ou geckodriver (Firefox); ambos são iniciados automaticamente a partir do PATH se já não estiverem em execução. pip install "wavexis-mcp[bidi]"

Selecione por sessão:

# 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 um Chrome existente

Use connect_existing=True para iniciar o Chrome com --remote-debugging-port e conectar-se a ele. Útil para reutilizar um perfil de navegador com sessões logadas:

# 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")

O Chrome é iniciado com interface gráfica (headless é ignorado). O subprocesso do navegador é encerrado quando a sessão é fechada.

YAML de múltiplas ações

Encadeie várias ações em uma única chamada de ferramenta passando uma string 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 ação suportados: navigate, screenshot, eval, click, type, fill. Defina continue_on_error: true para continuar executando em caso de falhas.

Recursos e prompts MCP (M3)

Recursos (estado do navegador somente leitura):

• wavexis://session/{id}/url — URL da página atual
• wavexis://session/{id}/cookies — cookies como JSON
• wavexis://session/{id}/console — mensagens do console
• wavexis://session/{id}/tabs — abas abertas

Prompts (modelos de fluxo de trabalho):

• scrape_page(url, selector) — extrair e coletar conteúdo
• audit_page(url) — auditoria completa de a11y + performance
• fill_form(url, fields) — preencher um formulário em uma página
• debug_page(url) — depurar console, rede, performance

Transporte HTTP

Execute o WaveXisMCP como um servidor HTTP para CI/CD, instâncias compartilhadas ou 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

Vincula-se a 127.0.0.1 por padrão. Use --allow-remote para 0.0.0.0.

Limite de taxa (M4)

Limite de taxa por sessão com token bucket:

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

Quando excedido, retorna {"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

Consulte a documentação do Docker para detalhes.

Comparação

Recurso	Playwright MCP	WaveXisMCP
Linguagem	TypeScript	Python
Node.js necessário	✗	✓ (sem Node.js)
Baixa Chromium (~200MB)	✓	✗ (usa navegador existente)
Tamanho da instalação	~400MB	~5MB
Inicialização a frio	3.2s	0.8s
Total de ferramentas	~21	220
Níveis de capacidade (opt-in)	✗	✓ (13 níveis)
Protocolo duplo (CDP + BiDi)	✗	✓
Suporte a Firefox	✓ (básico)	✓ (BiDi + inicialização automática do geckodriver)
Seleção de backend (por sessão)	✗	✓
Modo stealth / anti-bot	✗	✓
Acesso bruto a CDP/BiDi	✗	✓ (saída de emergência)
Lote YAML de múltiplas ações	✗	✓
Gravação de vídeo	✗	✓
Auditoria Lighthouse	✗	✓
WebAuthn / Bluetooth / Cast	✗	✓
Interação em linguagem natural	✗	✓ (wavexis_act)
Recursos e prompts MCP	✗	✓
Limite de taxa	✗	✓
Proteção SSRF	✗	✓
Erros estruturados com sugestões	✗	✓

Nota: O Playwright MCP suporta WebKit (Safari) — o WaveXisMCP não suporta (ainda). Consulte o roadmap para recursos planejados.

Documentação

Documentação completa, referência da API e exemplos estão hospedados em mathiaspaulenko.github.io/wavexis-mcp.

Seções principais:

• Início Rápido
• Arquitetura
• Configuração
• Docker
• Transporte HTTP
• Limite de Taxa
• Referência de Ferramentas
• Exemplos

Tratamento de erros

Todas as ferramentas retornam JSON de erro estruturado em caso de falha. Todo erro inclui um campo suggestion que orienta o LLM para a próxima ação:

{
  "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."
}

Isso permite que o LLM se autocorrija sem intervenção humana — ele lê a sugestão e chama a ferramenta recomendada.

Arquitetura

O WaveXisMCP está no topo de um ecossistema de três camadas:

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

• cdpwave — biblioteca Python assíncrona de baixo nível para o Chrome DevTools Protocol. WebSocket direto para Chrome/Edge. Sem necessidade de binário de driver.
• bidiwave — biblioteca Python assíncrona de baixo nível para o protocolo WebDriver BiDi (padrão W3C). Funciona com Firefox, Chrome e Edge.
• wavexis — biblioteca de automação de navegador de alto nível que abstrai cdpwave e bidiwave por trás de uma interface unificada AbstractBackend.
• WaveXisMCP — servidor MCP que encapsula wavexis. Expõe cada método de backend como uma ferramenta MCP com validação de entrada Pydantic v2, respostas JSON e filtragem por nível de capacidade.

Consulte a documentação de Arquitetura para o design completo do sistema, diagramas de fluxo de dados e ADRs.

Desenvolvimento

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

Contribuindo

Contribuições são bem-vindas. Consulte CONTRIBUTING.md para o fluxo de trabalho de desenvolvimento, padrões de codificação e processo de pull requests. Para problemas de segurança, consulte SECURITY.md.

Agradecimentos

WaveXisMCP é construído sobre a biblioteca de automação de navegador wavexis e o Model Context Protocol. Graças às comunidades open-source de Python e MCP pelas ferramentas e padrões que tornam este projeto possível.

Licença

MIT

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