wavexis-mcp

<p align="center"> <img src="docs/assets/images/logo-wide.svg" alt="WaveXisMCP" width="480"> </p> <h3 align="center">MCP server — 220 browser automation tools for LLMs</h3> --- [](https://github.com/MathiasPaulenko/wavexis-mcp/actions/workflows/ci.yml) [](https://pypi.org/project/wavexis-mcp/) [](https://pypi.org/project/wavexis-mcp/) [](https://github.com/MathiasPaulenko/wavexis-mcp/pkgs/container/wavexis-mcp) [](https://github.com/MathiasPaulenko/wavexis-mcp/blob/main/LICENSE) [](https://mathiaspaulenko.github.io/wavexis-mcp/) > MCP server that exposes the [wavexis](https://github.com/MathiasPaulenko/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](https://github.com/MathiasPaulenko/wavexis) browser automation library and exposes it as an [MCP server](https://modelcontextprotocol.io/). You don't need Node.js, Playwright, or a separate Chromium download — WaveXisMCP launches your existing Chrome or Edge installation directly. ### How it works ```text 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 ```bash pip install wavexis-mcp ``` With CDP backend (Chromium): ```bash pip install "wavexis-mcp[cdp]" ``` Or run without installing (recommended): ```bash 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): ```json { "mcpServers": { "wavexis": { "command": "uvx", "args": ["wavexis-mcp", "--caps", "all"] } } } ``` Or with pip: ```json { "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: ```text wavexis_screenshot(url="https://example.com", full_page=true) ``` ### Session mode (multi-step) Open a session, chain multiple actions, close when done: ```text 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: ```text 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 | Tier | Flag | Tools | Key features | |------|------|-------|--------------| | **Core** | always on | 72 | Session, navigation, screenshot, PDF, scrape, eval, DOM, input, cookies, tabs, NL interaction, iframe, shadow DOM, events | | **Network** | `--caps=network` | 20 | Headers, UA, block, throttle, cache, HAR, intercept, mock, modify req/resp, request body, replay HAR, request list | | **Storage** | `--caps=storage` | 18 | localStorage, sessionStorage, cache storage, IndexedDB, state save/restore | | **Emulation** | `--caps=emulation` | 9 | Device, viewport, geolocation, timezone, dark mode, locale, CPU, touch, sensors | | **A11y** | `--caps=a11y` | 4 | Accessibility tree snapshot, node traversal, axe-core audit | | **Interactions** | `--caps=interactions` | 5 | Dialogs, downloads, permissions | | **DevTools** | `--caps=devtools` | 31 | Performance, CSS, debugging, overlay, console, security, window mgmt, combined trace, annotated screenshot | | **Vision** | `--caps=vision` | 7 | Coordinate-based mouse (pixel-precise) | | **Video** | `--caps=video` | 4 | Video recording, chapters, action overlay | | **Testing** | `--caps=testing` | 6 | Assertions, locator generation | | **Workflows** | `--caps=workflows` | 6 | Multi-action YAML, raw CDP/BiDi, browser context CRUD | | **Data** | `--caps=data` | 7 | Codegen, Lighthouse audit, extract, websocket intercept, crawl, visual diff, core web vitals | | **Experimental** | `--caps=experimental` | 31 | Service workers, animations, WebAuthn, WebAudio, media, cast, bluetooth, extensions, prefs | | **Total** | `--caps=all` | **220** | | **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: ```text wavexis_session_open(backend="bidi") ``` ## Multi-action YAML Chain multiple actions in a single tool call by passing a YAML string: ```text 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: ```bash # 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: ```bash # 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 ```bash # 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](https://mathiaspaulenko.github.io/wavexis-mcp/docker/) for details. ## Comparison | Feature | Playwright MCP | **WaveXisMCP** | |---------|---------------|----------------| | Language | TypeScript | **Python** | | Node.js required | Yes | **No** | | Downloads Chromium | Yes (~200MB) | **No (uses existing Chrome/Edge)** | | Install size | ~200MB+ | **~5MB** | | Total tools | ~70 | **220** | | Capability tiers | Yes (`--caps`) | **Yes (13 tiers)** | | Dual protocol | No | **CDP + BiDi** | | Backend selection | No | **Yes (per session)** | | Raw CDP/BiDi access | No | **Yes (escape hatch)** | | Multi-action YAML | No | **Yes** | | Video recording | No | **Yes** | | Lighthouse audit | No | **Yes** | | WebAuthn/Bluetooth | No | **Yes** | | Natural language interaction | No | **Yes (`wavexis_act`)** | | MCP resources & prompts | No | **Yes** | | Rate limiting | No | **Yes** | ## Documentation Full documentation, API reference, and examples are hosted at [mathiaspaulenko.github.io/wavexis-mcp](https://mathiaspaulenko.github.io/wavexis-mcp/). Key sections: - [Quick Start](https://mathiaspaulenko.github.io/wavexis-mcp/quickstart/) - [Architecture](https://mathiaspaulenko.github.io/wavexis-mcp/architecture/) - [Configuration](https://mathiaspaulenko.github.io/wavexis-mcp/configuration/) - [Docker](https://mathiaspaulenko.github.io/wavexis-mcp/docker/) - [HTTP Transport](https://mathiaspaulenko.github.io/wavexis-mcp/http-transport/) - [Rate Limiting](https://mathiaspaulenko.github.io/wavexis-mcp/rate-limiting/) - [Tools Reference](https://mathiaspaulenko.github.io/wavexis-mcp/tools/core/) - [Examples](https://mathiaspaulenko.github.io/wavexis-mcp/examples/screenshot/) ## Error handling All tools return structured error JSON on failure. Every error includes a `suggestion` field that guides the LLM toward the next action: ```json { "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: ```text 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](https://mathiaspaulenko.github.io/wavexis-mcp/architecture/) for the full system design, data flow diagrams, and ADRs. ## Development ```bash 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](CONTRIBUTING.md) for the development workflow, coding standards, and pull request process. For security issues, see [SECURITY.md](SECURITY.md). ## Acknowledgements WaveXisMCP is built on the [wavexis](https://github.com/MathiasPaulenko/wavexis) browser automation library and the [Model Context Protocol](https://modelcontextprotocol.io/). Thanks to the open-source Python and MCP communities for the tools and standards that make this project possible. ## License MIT