Chrome + Firefox · CDP + BiDi · 100% Python · zero Node.js · zero Chromium download
--- **English** | [简体中文](README.zh-CN.md) | [日本語](README.ja.md) [](https://github.com/MathiasPaulenko/wavexis-mcp/actions/workflows/ci.yml) [](https://pypi.org/project/wavexis-mcp/) [](https://pypi.org/project/wavexis-mcp/) [](https://pypi.org/project/wavexis-mcp/) [](https://github.com/MathiasPaulenko/wavexis-mcp/actions/workflows/ci.yml) [](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/) [](https://smithery.ai/servers/mathias-paulenko/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. ## Quick demo **30 seconds to your first screenshot.** Add this to your MCP client config (Claude Desktop, Cursor, Windsurf, VS Code): ```json { "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](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. ### 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 - **700+ tests, 90% coverage enforced, E2E with real Chrome** — production-ready ### 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/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 ```bash pip install wavexis-mcp ``` The CDP backend (Chromium) is included by default. For the BiDi backend (Firefox): ```bash pip install "wavexis-mcp[bidi]" ``` 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 Chrome, or geckodriver for Firefox ## 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. Included by default. - **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: ```text # 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: ```text # 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: ```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, the tool returns the standard structured error: `{"error": "Rate limit exceeded. Retry after Nms.", "type": "RuntimeError", ...}`. Set `--rate-limit 0` to disable. ## 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 | ✗ | **✓ (no Node.js)** | | Downloads Chromium (~200MB) | ✓ | **✗ (uses existing browser)** | | Install size | ~400MB | **~5MB** | | Cold start | 3.2s | **0.8s** | | Total tools | ~21 | **220** | | Capability tiers (opt-in) | ✗ | **✓ (13 tiers)** | | Dual protocol (CDP + BiDi) | ✗ | **✓** | | Firefox support | ✓ (basic) | **✓ (BiDi + geckodriver auto-launch)** | | Backend selection (per session) | ✗ | **✓** | | Stealth / anti-bot mode | ✗ | **✓** | | Raw CDP/BiDi access | ✗ | **✓ (escape hatch)** | | Multi-action YAML batching | ✗ | **✓** | | Video recording | ✗ | **✓** | | Lighthouse audit | ✗ | **✓** | | WebAuthn / Bluetooth / Cast | ✗ | **✓** | | Natural language interaction | ✗ | **✓ (`wavexis_act`)** | | MCP resources & prompts | ✗ | **✓** | | Rate limiting | ✗ | **✓** | | SSRF protection | ✗ | **✓** | | Structured errors with suggestions | ✗ | **✓** | > **Note**: Playwright MCP supports WebKit (Safari) — WaveXisMCP does not (yet). See the [roadmap](https://github.com/MathiasPaulenko/wavexis-mcp/issues) for planned features. ## 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 mcp-name: io.github.MathiasPaulenko/wavexis-mcp