Wavexis MCP README

MCP server — 220 browser automation tools for LLMs

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

English | 简体中文 | 日本語

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

Quick demo

30 seconds to your first screenshot. Add this to your MCP client config (Claude Desktop, Cursor, Windsurf, VS Code):

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

Then ask your LLM:

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

The LLM calls wavexis_screenshot(url="https://example.com", full_page=true) and returns the screenshot. No Node.js, no Chromium download, no setup beyond the config above.

Why WaveXisMCP?

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

Key features

• 220 tools — 3x more than Playwright MCP (21), 2x more than zendriver-mcp (96)
• 13 capability tiers — enable only what you need via --caps. Start with core (72 tools), add tiers as needed
• Chrome + Firefox — CDP for Chrome/Edge, BiDi for Firefox. Both auto-launch their drivers from PATH
• No Chromium download — uses your existing browser. ~5MB install vs ~400MB for Playwright MCP
• Stealth mode — stealth=true hides navigator.webdriver, fakes plugins/languages/chrome runtime
• Structured errors — every error includes a suggestion field so the LLM self-corrects without human help
• Multi-action YAML — chain navigate → click → fill → screenshot in a single tool call
• Raw CDP/BiDi access — escape hatch for any browser feature not covered by a dedicated tool
• Lighthouse audits, WebAuthn, Bluetooth, Cast — niche features no other MCP server covers
• SSRF protection, path sandboxing, rate limiting — security built in from day one
• 593 tests, 90% coverage enforced, E2E with real Chrome — production-ready

How it works

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

The LLM never sees the browser directly. It only sees tool definitions (name, description, parameters) and JSON responses. This means any MCP-compatible LLM client works out of the box — no custom integrations needed.

Core concepts

• Tool — A single browser operation (screenshot, eval, click, etc.) exposed as an MCP tool that any LLM client can call.
• Session — A persistent browser instance. Open a session, chain multiple tool calls, close when done. Avoids the overhead of launching a browser per action.
• Stateless mode — Call any tool with a url parameter. The browser launches, executes, and closes automatically.
• Capability tiers — 13 tiers from core (72 tools) to all (220 tools). Enable only what you need via --caps.
• Dual backend — CDP (Chromium-native, via cdpwave) and BiDi (W3C cross-browser, via bidiwave) with per-session selection.
• Structured errors — Every error includes a suggestion field that tells the LLM what to do next, enabling self-correction without human intervention.

Install

pip install wavexis-mcp

With CDP backend (Chromium):

pip install "wavexis-mcp[cdp]"

Or run without installing (recommended):

uvx wavexis-mcp

Requirements

• 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

Quick start

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

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

Or with pip:

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

Stateless mode (one-shot)

Call any tool with a url parameter — the browser launches, executes, and closes automatically:

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

Session mode (multi-step)

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

Natural language interaction (M1)

Use wavexis_act to 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"}

The wavexis_act tool 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.

Capability tiers

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

Tip: Start with --caps core and 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.

Backends

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

Select per session:

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

Connect to existing Chrome

Use connect_existing=True to launch Chrome with --remote-debugging-port and connect to it. Useful for reusing a browser profile with logged-in sessions:

# 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 is launched headed (headless is ignored). The browser subprocess is terminated when the session is closed.

Multi-action YAML

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. Set continue_on_error: true to keep executing on failures.

MCP resources & prompts (M3)

Resources (read-only browser state):

• wavexis://session/{id}/url — current page URL
• wavexis://session/{id}/cookies — cookies as JSON
• wavexis://session/{id}/console — console messages
• wavexis://session/{id}/tabs — open tabs

Prompts (workflow templates):

• 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

HTTP transport

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 to 127.0.0.1 by default. Use --allow-remote for 0.0.0.0.

Rate limiting (M4)

Per-session token bucket rate limiting:

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

When exceeded, returns {"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

See Docker docs for details.

Comparison

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

Documentation

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

Key sections:

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

Error handling

All tools return structured error JSON on failure. Every error includes a suggestion field that guides the LLM toward the next action:

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

This enables the LLM to self-correct without human intervention — it reads the suggestion and calls the recommended tool.

Architecture

WaveXisMCP sits at the top of a three-layer ecosystem:

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

• cdpwave — low-level async Python library for the Chrome DevTools Protocol. Direct WebSocket to Chrome/Edge. No driver binary needed.
• bidiwave — low-level async Python library for the WebDriver BiDi protocol (W3C standard). Works with Firefox, Chrome, and Edge.
• wavexis — high-level browser automation library that abstracts cdpwave and bidiwave behind a unified AbstractBackend interface.
• WaveXisMCP — MCP server wrapping wavexis. Exposes each backend method as an MCP tool with Pydantic v2 input validation, JSON responses, and capability tier filtering.

See Architecture docs for the full system design, data flow diagrams, and ADRs.

Development

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

Contributing

Contributions are welcome. Please see CONTRIBUTING.md for the development workflow, coding standards, and pull request process. For security issues, see SECURITY.md.

Acknowledgements

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

License

MIT

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