WaveXisMCP
220 browser automation tools for Chrome, Edge, and Firefox via CDP + BiDi. 100% Python.
Open source Open in the app JSON README (API)
About
220 browser automation tools for Chrome, Edge, and Firefox via CDP + BiDi. 100% Python.
Details
- Kind
- MCP servers
- Topic
- Web search, scraping & browser
- Publisher
- mathiaspaulenko
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.6.24
- Stars
- 1
- Forks
- 1
- Open pull requests
- 1
- Last push
- 2026-08-29T10:23:20Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 03:02:05
- Updated
- 2026-08-29 03:02:05
- Origin id
io.github.MathiasPaulenko/wavexis-mcp
README
<!-- 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>
---
**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
- **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 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, 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 | ✗ | **✓ (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 -->
mcp-name: io.github.MathiasPaulenko/wavexis-mcp