wavexis-mcp 1.6.21

MCP server — 220 browser automation tools for LLMs

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.

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.

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 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 W3C WebDriver BiDi

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/EdgeDriver. pip install "wavexis-mcp[bidi]"

Select per session:

wavexis_session_open(backend="bidi")

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

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