wavexis-mcp

<!-- mcp-name: io.github.MathiasPaulenko/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>

<p align="center">
  <strong>Chrome + Firefox · CDP + BiDi · 100% Python · zero Node.js · zero Chromium download</strong>
</p>

---

[![CI](https://github.com/MathiasPaulenko/wavexis-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/MathiasPaulenko/wavexis-mcp/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/wavexis-mcp.svg)](https://pypi.org/project/wavexis-mcp/)
[![PyPI Downloads](https://img.shields.io/pypi/dm/wavexis-mcp.svg)](https://pypi.org/project/wavexis-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/wavexis-mcp.svg)](https://pypi.org/project/wavexis-mcp/)
[![Coverage](https://img.shields.io/badge/coverage-90%25-brightgreen.svg)](https://github.com/MathiasPaulenko/wavexis-mcp/actions/workflows/ci.yml)
[![Docker](https://img.shields.io/badge/Docker-ghcr.io-blue.svg)](https://github.com/MathiasPaulenko/wavexis-mcp/pkgs/container/wavexis-mcp)
[![License](https://img.shields.io/github/license/MathiasPaulenko/wavexis-mcp.svg)](https://github.com/MathiasPaulenko/wavexis-mcp/blob/main/LICENSE)
[![Docs](https://img.shields.io/badge/docs-mkdocs-blue.svg)](https://mathiaspaulenko.github.io/wavexis-mcp/)
[![smithery badge](https://smithery.ai/badge/mathias-paulenko/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
- **593 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
```

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 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. `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:

```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 w