WaveXisMCP

MCP server — 220 browser automation tools for LLMs

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

MCP server that exposes thewavexisbrowser automation library to LLMs. 220 tools across 13 capability tiers. No Node.js, no Chromium download — uses your existing Chrome/Edge. 100% Python.

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

"Take a full-page screenshot ofhttps://example.com"

WaveXisMCP wraps thewavexisbrowser automation library and exposes it as anMCP server. You don't need Node.js, Playwright, or a separate Chromium download — WaveXisMCP launches your existing Chrome or Edge installation directly.

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

pip install "wavexis-mcp[cdp]"

Or run without installing (recommended):

- Python: 3.11, 3.12, or 3.13
- Browser: Google Chrome, Microsoft Edge, or any Chromium/Chrome-based browser
- BiDi backend(optional): ChromeDriver/EdgeDriver for Chrome, or geckodriver for Firefox

Add to your MCP client config (Claude Desktop, Cursor, Windsurf, VS Code):

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

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

Call any tool with aurlparameter — the browser launches, executes, and closes automatically:

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

Open a session, chain multiple actions, close when done:

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

Usewavexis_actto interact with pages using natural language:

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

Thewavexis_acttool takes an a11y snapshot, matches the instruction to an element using keyword scoring, and executes the detected action (click, type, fill, hover). No external LLM calls — pure heuristic matching.

Default:--caps=core(72 tools). Enable all:--caps=all. Enable specific:--caps=network,storage,emulation.

Tip: Start with--caps coreand add tiers as needed. Each tier adds tool definitions to the LLM's context, which consumes tokens. For most tasks,core,network,storage(110 tools) is a good balance.

WaveXisMCP supports two backends with full feature parity:

- CDP(cdpwave) — default, Chrome DevTools Protocol. Direct WebSocket to Chrome/Edge. No driver needed. 57 CDP domains.pip install "wavexis-mcp[cdp]"
- BiDi(bidiwave) — WebDriver BiDi protocol, W3C cross-browser (Firefox, Chrome). Needs chromedriver (Chrome) or geckodriver (Firefox); both are auto-launched from PATH if not already running.pip install "wavexis-mcp[bidi]"

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

Useconnect_existing=Trueto launch Chrome with--remote-debugging-portand connect to it. Useful for reusing a browser profile with logged-in sessions:

Chrome is launched headed (headless is ignored). The browser subprocess is terminated when the session is closed.

Chain multiple actions in a single tool call by passing a YAML string:

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

Supported action types:navigate,screenshot,eval,click,type,fill. Setcontinue_on_error: trueto keep executing on failures.

- scrape_page(url, selector)— scrape and extract content
- audit_page(url)— full a11y + performance audit
- fill_form(url, fields)— fill a form on a page
- debug_page(url)— debug console, network, performance

Run WaveXisMCP as an HTTP server for CI/CD, shared instances, or 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

Binds to127.0.0.1by default. Use--allow-remotefor0.0.0.0.

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

When exceeded, returns{"error": "rate_limited", "retry_after_ms": N}.

# 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

Note: Playwright MCP supports WebKit (Safari) — WaveXisMCP does not (yet). See theroadmapfor planned features.

Full documentation, API reference, and examples are hosted atmathiaspaulenko.github.io/wavexis-mcp.

- Quick Start
- Architecture
- Configuration
- Docker
- HTTP Transport
- Rate Limiting
- Tools Reference
- Examples

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

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

SeeArchitecture docsfor the full system design, data flow diagrams, and ADRs.

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

Contributions are welcome. Please seeCONTRIBUTING.mdfor the development workflow, coding standards, and pull request process. For security issues, seeSECURITY.md.

WaveXisMCP is built on thewavexisbrowser automation library and theModel Context Protocol. Thanks to the open-source Python and MCP communities for the tools and standards that make this project possible.

Real-time web data, structured for agents