WaveXisMCP

MCP server — 220 browser automation tools for LLMs

Chrome + Firefox · CDP + BiDi · 100% Python · zero Node.js · zero Chromium download

---

English | 简体中文 | 日本語

MCP server that exposes the 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):

{

"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 browser automation library and exposes it as an MCP server. 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

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

pip install wavexis-mcp

The CDP backend (Chromium) is included by default. For the BiDi backend (Firefox):

pip install "wavexis-mcp[bidi]"

Or run without installing (recommended):

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):

{

"mcpServers": { "wavexis": { "command": "uvx", "args": ["wavexis-mcp", "--caps", "all"] } } }

Or with pip:

{

"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:

wavexis_screenshot(url="https://example.com", full_page=true)

Session mode (multi-step)

Open a session, chain multiple actions, close when done:

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:

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

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:

# 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:

# 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:

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:

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