Skip to content

Quick Start

This guide walks you through installing WaveXisMCP, configuring it in your LLM client, and making your first browser automation tool call.

Prerequisites

  • Python 3.11+ — WaveXisMCP requires Python 3.11 or newer
  • Chrome or Edge — a Chromium-based browser installed on your machine (Chrome, Edge, Brave, Chromium). WaveXisMCP launches your existing browser — no separate Chromium download.
  • An MCP-compatible LLM client — Claude Desktop, Cursor, Windsurf, VS Code with MCP support, or any client that speaks the Model Context Protocol

No Node.js required

Unlike Playwright MCP, WaveXisMCP is 100% Python. You do not need Node.js, npm, or any JavaScript runtime.

Install

pip install wavexis-mcp

With CDP backend (Chromium-native, no driver needed):

pip install "wavexis-mcp[cdp]"

With BiDi backend (W3C cross-browser, supports Firefox + Chrome):

pip install "wavexis-mcp[bidi]"

With both backends:

pip install "wavexis-mcp[cdp,bidi]"

uvx wavexis-mcp

uvx downloads WaveXisMCP into an isolated environment and runs it. No virtualenv needed. This is the easiest way to use WaveXisMCP — just point your MCP client at uvx wavexis-mcp.

Verify installation

wavexis-mcp --help

You should see output listing available CLI flags, capability tiers, and transport options.

Configure your MCP client

WaveXisMCP runs as a stdio MCP server by default. Your LLM client launches it as a subprocess and communicates over stdin/stdout.

Claude Desktop

Add to claude_desktop_config.json (typically at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):

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

Cursor / Windsurf / VS Code

Add to your MCP settings:

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

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

Capability tiers

The --caps flag controls which tools are exposed to the LLM. With 220 tools total, exposing all of them can overwhelm smaller LLMs with long tool lists. Choose a tier that matches your use case:

Flag Tools Use case
--caps core 72 Default. Session, navigation, screenshot, DOM, input. Good for simple tasks.
--caps core,network,storage 110 Add network control and storage access. Good for scraping.
--caps core,a11y,interactions,devtools 112 Add accessibility, dialogs, and DevTools. Good for testing.
--caps all 220 Everything. Good for power users and automation.

See Configuration for the full list of tiers.

First tool call

Once configured, restart your LLM client and ask it to use a tool:

Take a screenshot of https://example.com

The LLM will:

  1. Call wavexis_screenshot(url="https://example.com")
  2. WaveXisMCP launches Chrome/Edge in headless mode
  3. Navigates to https://example.com
  4. Captures a screenshot
  5. Returns it as base64-encoded PNG
  6. Closes the browser
  7. The LLM receives the screenshot and shows it to you

This is stateless mode — the browser launches, executes one action, and closes automatically. No session management needed.

Session-based workflow

For multi-step tasks (navigate → click → fill → screenshot), use sessions. A session keeps the browser open across multiple tool calls:

# 1. Open a session — launches Chrome/Edge and keeps it running
wavexis_session_open(backend="cdp", headless=false)
→ {"session_id": "abc-123"}

# 2. Navigate to a page
wavexis_navigate(session_id="abc-123", url="https://example.com")

# 3. Click a button
wavexis_click(session_id="abc-123", selector="#login")

# 4. Fill a form field
wavexis_fill(session_id="abc-123", selector="#email", value="user@example.com")

# 5. Take a screenshot to verify
wavexis_screenshot(session_id="abc-123")

# 6. Close the session — kills the browser process
wavexis_session_close(session_id="abc-123")

Why sessions?

Stateless Session
Browser launches per call Browser launches once
Browser closes after call Browser stays open
No state between calls Full state (cookies, localStorage, page context)
Good for one-shot tasks Good for multi-step workflows
Pass url= parameter Pass session_id= parameter

Backend selection

When opening a session, choose your backend:

# CDP — Chromium-native, no driver needed (default, recommended)
wavexis_session_open(backend="cdp")

# BiDi with Chrome — auto-launches chromedriver from PATH
wavexis_session_open(backend="bidi", browser="chrome")

# BiDi with Firefox — auto-launches geckodriver from PATH
wavexis_session_open(backend="bidi", browser="firefox")

CDP is recommended for Chrome/Edge only. BiDi enables Firefox support and auto-launches the appropriate driver (chromedriver or geckodriver) from PATH if one is not already running.

Connect to existing Chrome

Use connect_existing=True to launch Chrome with --remote-debugging-port and connect to it via CDP. This is useful for reusing a browser profile with logged-in sessions:

# Launch Chrome with debug port (uses a temp profile)
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.

Natural language interaction

The wavexis_act tool (requires --caps=a11y) lets the LLM interact with pages using natural language instead of CSS selectors:

wavexis_session_open(backend="cdp")
wavexis_navigate(session_id="abc-123", url="https://example.com")

# The LLM can say "click the login button" instead of knowing the selector
wavexis_act(session_id="abc-123", instruction="click the login button")
→ {"action": "click", "element": {"ref": "el-3", "role": "button", "name": "Login"}, "status": "ok"}

wavexis_session_close(session_id="abc-123")

wavexis_act takes an accessibility snapshot, matches the instruction to an element using keyword scoring, and executes the detected action. No external LLM calls — pure heuristic matching.

Next steps