![\"WaveXisMCP\"](\"docs/assets/images/logo-wide.svg\"){kind=logo}
\n\n \n
\n Chrome + Firefox · CDP + BiDi · 100% Python · zero Node.js · zero Chromium download\n
\n\n---\n\n**English** | [简体中文](README.zh-CN.md) | [日本語](README.ja.md)\n\n[](https://github.com/MathiasPaulenko/wavexis-mcp/actions/workflows/ci.yml)\n[](https://pypi.org/project/wavexis-mcp/)\n[](https://pypi.org/project/wavexis-mcp/)\n[](https://pypi.org/project/wavexis-mcp/)\n[](https://github.com/MathiasPaulenko/wavexis-mcp/actions/workflows/ci.yml)\n[](https://github.com/MathiasPaulenko/wavexis-mcp/pkgs/container/wavexis-mcp)\n[](https://github.com/MathiasPaulenko/wavexis-mcp/blob/main/LICENSE)\n[](https://mathiaspaulenko.github.io/wavexis-mcp/)\n[](https://smithery.ai/servers/mathias-paulenko/wavexis-mcp)\n\n> 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.\n\n## Quick demo\n\n**30 seconds to your first screenshot.** Add this to your MCP client config (Claude Desktop, Cursor, Windsurf, VS Code):\n\n```json\n{\n \"mcpServers\": {\n \"wavexis\": {\n \"command\": \"uvx\",\n \"args\": [\"wavexis-mcp\", \"--caps\", \"all\"]\n }\n }\n}\n```\n\nThen ask your LLM:\n\n> *\"Take a full-page screenshot of https://example.com\"*\n\nThe 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.\n\n## Why WaveXisMCP?\n\nWaveXisMCP 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.\n\n### Key features\n\n- **220 tools** — 3x more than Playwright MCP (21), 2x more than zendriver-mcp (96)\n- **13 capability tiers** — enable only what you need via `--caps`. Start with `core` (72 tools), add tiers as needed\n- **Chrome + Firefox** — CDP for Chrome/Edge, BiDi for Firefox. Both auto-launch their drivers from PATH\n- **No Chromium download** — uses your existing browser. ~5MB install vs ~400MB for Playwright MCP\n- **Stealth mode** — `stealth=true` hides `navigator.webdriver`, fakes plugins/languages/chrome runtime\n- **Structured errors** — every error includes a `suggestion` field so the LLM self-corrects without human help\n- **Multi-action YAML** — chain navigate → click → fill → screenshot in a single tool call\n- **Raw CDP/BiDi access** — escape hatch for any browser feature not covered by a dedicated tool\n- **Lighthouse audits, WebAuthn, Bluetooth, Cast** — niche features no other MCP server covers\n- **SSRF protection, path sandboxing, rate limiting** — security built in from day one\n- **593 tests, 90% coverage enforced, E2E with real Chrome** — production-ready\n\n### How it works\n\n```text\nYou (natural language)\n → LLM decides which tool to call\n → WaveXisMCP receives the tool call\n → wavexis library executes it via CDP or BiDi\n → Chrome/Edge/Firefox performs the action\n ← Result returned as JSON (text, base64, file path)\n ← JSON passed back to LLM\n ← LLM summarizes the result for you\n```\n\nThe 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.\n\n### Core concepts\n\n- **Tool** — A single browser operation (screenshot, eval, click, etc.) exposed as an MCP tool that any LLM client can call.\n- **Session** — A persistent browser instance. Open a session, chain multiple tool calls, close when done. Avoids the overhead of launching a browser per action.\n- **Stateless mode** — Call any tool with a `url` parameter. The browser launches, executes, and closes automatically.\n- **Capability tiers** — 13 tiers from `core` (72 tools) to `all` (220 tools). Enable only what you need via `--caps`.\n- **Dual backend** — CDP (Chromium-native, via cdpwave) and BiDi (W3C cross-browser, via bidiwave) with per-session selection.\n- **Structured errors** — Every error includes a `suggestion` field that tells the LLM what to do next, enabling self-correction without human intervention.\n\n## Install\n\n```bash\npip install wavexis-mcp\n```\n\nWith CDP backend (Chromium):\n\n```bash\npip install \"wavexis-mcp[cdp]\"\n```\n\nOr run without installing (recommended):\n\n```bash\nuvx wavexis-mcp\n```\n\n## Requirements\n\n- **Python**: 3.11, 3.12, or 3.13\n- **Browser**: Google Chrome, Microsoft Edge, or any Chromium/Chrome-based browser\n- **BiDi backend** (optional): ChromeDriver/EdgeDriver for Chrome, or geckodriver for Firefox\n\n## Quick start\n\nAdd to your MCP client config (Claude Desktop, Cursor, Windsurf, VS Code):\n\n```json\n{\n \"mcpServers\": {\n \"wavexis\": {\n \"command\": \"uvx\",\n \"args\": [\"wavexis-mcp\", \"--caps\", \"all\"]\n }\n }\n}\n```\n\nOr with pip:\n\n```json\n{\n \"mcpServers\": {\n \"wavexis\": {\n \"command\": \"wavexis-mcp\",\n \"args\": [\"--caps\", \"all\"]\n }\n }\n}\n```\n\n### Stateless mode (one-shot)\n\nCall any tool with a `url` parameter — the browser launches, executes, and closes automatically:\n\n```text\nwavexis_screenshot(url=\"https://example.com\", full_page=true)\n```\n\n### Session mode (multi-step)\n\nOpen a session, chain multiple actions, close when done:\n\n```text\nwavexis_session_open(backend=\"cdp\", headless=false)\n→ {\"session_id\": \"abc-123\"}\n\nwavexis_navigate(session_id=\"abc-123\", url=\"https://example.com\")\nwavexis_click(session_id=\"abc-123\", selector=\"#login\")\nwavexis_screenshot(session_id=\"abc-123\")\nwavexis_session_close(session_id=\"abc-123\")\n```\n\n### Natural language interaction (M1)\n\nUse `wavexis_act` to interact with pages using natural language:\n\n```text\nwavexis_session_open(backend=\"cdp\")\nwavexis_navigate(session_id=\"abc-123\", url=\"https://example.com\")\nwavexis_act(session_id=\"abc-123\", instruction=\"click the login button\")\n→ {\"action\": \"click\", \"element\": {\"ref\": \"el-3\", \"role\": \"button\", \"name\": \"Login\"}, \"status\": \"ok\"}\n```\n\nThe `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.\n\n## Capability tiers\n\n| Tier | Flag | Tools | Key features |\n|------|------|-------|--------------|\n| **Core** | always on | 72 | Session, navigation, screenshot, PDF, scrape, eval, DOM, input, cookies, tabs, NL interaction, iframe, shadow DOM, events |\n| **Network** | `--caps=network` | 20 | Headers, UA, block, throttle, cache, HAR, intercept, mock, modify req/resp, request body, replay HAR, request list |\n| **Storage** | `--caps=storage` | 18 | localStorage, sessionStorage, cache storage, IndexedDB, state save/restore |\n| **Emulation** | `--caps=emulation` | 9 | Device, viewport, geolocation, timezone, dark mode, locale, CPU, touch, sensors |\n| **A11y** | `--caps=a11y` | 4 | Accessibility tree snapshot, node traversal, axe-core audit |\n| **Interactions** | `--caps=interactions` | 5 | Dialogs, downloads, permissions |\n| **DevTools** | `--caps=devtools` | 31 | Performance, CSS, debugging, overlay, console, security, window mgmt, combined trace, annotated screenshot |\n| **Vision** | `--caps=vision` | 7 | Coordinate-based mouse (pixel-precise) |\n| **Video** | `--caps=video` | 4 | Video recording, chapters, action overlay |\n| **Testing** | `--caps=testing` | 6 | Assertions, locator generation |\n| **Workflows** | `--caps=workflows` | 6 | Multi-action YAML, raw CDP/BiDi, browser context CRUD |\n| **Data** | `--caps=data` | 7 | Codegen, Lighthouse audit, extract, websocket intercept, crawl, visual diff, core web vitals |\n| **Experimental** | `--caps=experimental` | 31 | Service workers, animations, WebAuthn, WebAudio, media, cast, bluetooth, extensions, prefs |\n| **Total** | `--caps=all` | **220** | |\n\n**Default**: `--caps=core` (72 tools). Enable all: `--caps=all`. Enable specific: `--caps=network,storage,emulation`.\n\n> **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.\n\n## Backends\n\nWaveXisMCP supports two backends with full feature parity:\n\n- **CDP** (cdpwave) — default, Chrome DevTools Protocol. Direct WebSocket to Chrome/Edge. No driver needed. 57 CDP domains. `pip install \"wavexis-mcp[cdp]\"`\n- **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]\"`\n\nSelect per session:\n\n```text\n# CDP (default, Chrome/Edge only)\nwavexis_session_open(backend=\"cdp\")\n\n# BiDi with Chrome (auto-launches chromedriver)\nwavexis_session_open(backend=\"bidi\", browser=\"chrome\")\n\n# BiDi with Firefox (auto-launches geckodriver)\nwavexis_session_open(backend=\"bidi\", browser=\"firefox\")\n```\n\n### Connect to existing Chrome\n\nUse `connect_existing=True` to launch Chrome with `--remote-debugging-port` and connect to it. Useful for reusing a browser profile with logged-in sessions:\n\n```text\n# Launch Chrome with debug port and connect via CDP\nwavexis_session_open(connect_existing=true)\n\n# Reuse an existing Chrome profile (keeps logins, cookies, extensions)\nwavexis_session_open(connect_existing=true, user_data_dir=\"C:/Users/me/ChromeProfile\")\n```\n\nChrome is launched headed (headless is ignored). The browser subprocess is terminated when the session is closed.\n\n## Multi-action YAML\n\nChain multiple actions in a single tool call by passing a YAML string:\n\n```text\nwavexis_multi_action(\n config=\"\"\"\nactions:\n - navigate: https://example.com\n - screenshot:\n full_page: true\n - eval: document.title\n - click: \"#login\"\n - type:\n selector: \"#username\"\n text: admin@example.com\n - screenshot: {}\n\"\"\",\n session_id=\"abc-123\"\n)\n```\n\nSupported action types: `navigate`, `screenshot`, `eval`, `click`, `type`, `fill`. Set `continue_on_error: true` to keep executing on failures.\n\n## MCP resources & prompts (M3)\n\n**Resources** (read-only browser state):\n\n- `wavexis://session/{id}/url` — current page URL\n- `wavexis://session/{id}/cookies` — cookies as JSON\n- `wavexis://session/{id}/console` — console messages\n- `wavexis://session/{id}/tabs` — open tabs\n\n**Prompts** (workflow templates):\n\n- `scrape_page(url, selector)` — scrape and extract content\n- `audit_page(url)` — full a11y + performance audit\n- `fill_form(url, fields)` — fill a form on a page\n- `debug_page(url)` — debug console, network, performance\n\n## HTTP transport\n\nRun WaveXisMCP as an HTTP server for CI/CD, shared instances, or Docker:\n\n```bash\n# HTTP on localhost\nwavexis-mcp --transport http --port 8765\n\n# HTTP with all tiers\nwavexis-mcp --transport http --port 8765 --caps all\n\n# HTTP with remote access (use behind a reverse proxy!)\nwavexis-mcp --transport http --allow-remote --port 8765\n```\n\nBinds to `127.0.0.1` by default. Use `--allow-remote` for `0.0.0.0`.\n\n## Rate limiting (M4)\n\nPer-session token bucket rate limiting:\n\n```bash\n# 10 calls/sec, burst of 5\nwavexis-mcp --rate-limit 10 --rate-burst 5\n```\n\nWhen exceeded, returns `{\"error\": \"rate_limited\", \"retry_after_ms\": N}`.\n\n## Docker\n\n```bash\n# Pull and run\ndocker run -p 8765:8765 ghcr.io/mathiaspaulenko/wavexis-mcp\n\n# Or build locally\ndocker build -t wavexis-mcp .\ndocker run -p 8765:8765 wavexis-mcp\n\n# Docker Compose\ndocker-compose up\n```\n\nSee [Docker docs](https://mathiaspaulenko.github.io/wavexis-mcp/docker/) for details.\n\n## Comparison\n\n| Feature | Playwright MCP | **WaveXisMCP** |\n|---------|:---:|:---:|\n| Language | TypeScript | **Python** |\n| Node.js required | ✗ | **✓ (no Node.js)** |\n| Downloads Chromium (~200MB) | ✓ | **✗ (uses existing browser)** |\n| Install size | ~400MB | **~5MB** |\n| Cold start | 3.2s | **0.8s** |\n| Total tools | ~21 | **220** |\n| Capability tiers (opt-in) | ✗ | **✓ (13 tiers)** |\n| Dual protocol (CDP + BiDi) | ✗ | **✓** |\n| Firefox support | ✓ (basic) | **✓ (BiDi + geckodriver auto-launch)** |\n| Backend selection (per session) | ✗ | **✓** |\n| Stealth / anti-bot mode | ✗ | **✓** |\n| Raw CDP/BiDi access | ✗ | **✓ (escape hatch)** |\n| Multi-action YAML batching | ✗ | **✓** |\n| Video recording | ✗ | **✓** |\n| Lighthouse audit | ✗ | **✓** |\n| WebAuthn / Bluetooth / Cast | ✗ | **✓** |\n| Natural language interaction | ✗ | **✓ (`wavexis_act`)** |\n| MCP resources & prompts | ✗ | **✓** |\n| Rate limiting | ✗ | **✓** |\n| SSRF protection | ✗ | **✓** |\n| Structured errors with suggestions | ✗ | **✓** |\n\n> **Note**: Playwright MCP supports WebKit (Safari) — WaveXisMCP does not (yet). See the [roadmap](https://github.com/MathiasPaulenko/wavexis-mcp/issues) for planned features.\n\n## Documentation\n\nFull documentation, API reference, and examples are hosted at [mathiaspaulenko.github.io/wavexis-mcp](https://mathiaspaulenko.github.io/wavexis-mcp/).\n\nKey sections:\n\n- [Quick Start](https://mathiaspaulenko.github.io/wavexis-mcp/quickstart/)\n- [Architecture](https://mathiaspaulenko.github.io/wavexis-mcp/architecture/)\n- [Configuration](https://mathiaspaulenko.github.io/wavexis-mcp/configuration/)\n- [Docker](https://mathiaspaulenko.github.io/wavexis-mcp/docker/)\n- [HTTP Transport](https://mathiaspaulenko.github.io/wavexis-mcp/http-transport/)\n- [Rate Limiting](https://mathiaspaulenko.github.io/wavexis-mcp/rate-limiting/)\n- [Tools Reference](https://mathiaspaulenko.github.io/wavexis-mcp/tools/core/)\n- [Examples](https://mathiaspaulenko.github.io/wavexis-mcp/examples/screenshot/)\n\n## Error handling\n\nAll tools return structured error JSON on failure. Every error includes a `suggestion` field that guides the LLM toward the next action:\n\n```json\n{\n \"error\": \"Session 'abc-123' not found.\",\n \"tool\": \"wavexis_navigate\",\n \"type\": \"SessionNotFoundError\",\n \"message\": \"Session 'abc-123' not found.\",\n \"suggestion\": \"Call wavexis_session_open first to create a browser session.\"\n}\n```\n\nThis enables the LLM to self-correct without human intervention — it reads the suggestion and calls the recommended tool.\n\n## Architecture\n\nWaveXisMCP sits at the top of a three-layer ecosystem:\n\n```text\nWaveXisMCP (MCP server, 220 tools)\n└─ wraps → wavexis (browser automation library)\n ├─ cdpwave (CDP backend, Chromium-native)\n └─ bidiwave (BiDi backend, W3C cross-browser)\n```\n\n- **cdpwave** — low-level async Python library for the Chrome DevTools Protocol. Direct WebSocket to Chrome/Edge. No driver binary needed.\n- **bidiwave** — low-level async Python library for the WebDriver BiDi protocol (W3C standard). Works with Firefox, Chrome, and Edge.\n- **wavexis** — high-level browser automation library that abstracts cdpwave and bidiwave behind a unified `AbstractBackend` interface.\n- **WaveXisMCP** — MCP server wrapping wavexis. Exposes each backend method as an MCP tool with Pydantic v2 input validation, JSON responses, and capability tier filtering.\n\nSee [Architecture docs](https://mathiaspaulenko.github.io/wavexis-mcp/architecture/) for the full system design, data flow diagrams, and ADRs.\n\n## Development\n\n```bash\ngit clone https://github.com/MathiasPaulenko/wavexis-mcp.git\ncd wavexis-mcp\npip install -e \".[dev]\"\n\n# Run quality checks\nruff check wavexis_mcp tests\nruff format --check\nmypy wavexis_mcp\npython -m bandit -r wavexis_mcp\n\n# Run tests\npytest tests/unit -v\n```\n\n## Contributing\n\nContributions 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).\n\n## Acknowledgements\n\nWaveXisMCP 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.\n\n## License\n\nMIT\n\n\nmcp-name: io.github.MathiasPaulenko/wavexis-mcp\n", "bytes": 16967, "sha": "23af4289b72ca3aed5dddeb5cecb9418b342c1fadda248c4bf02448f2c6f201b", "repo_slug": "mathiaspaulenko/wavexis-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_mathiaspaulenko_wavexis_mcp_844cbdd9/readme" }