Configuration¶
WaveXisMCP organizes 220 tools into 13 capability tiers. Core is always enabled. Additional tiers are opt-in via --caps.
Capability tiers¶
Capability tiers are the primary way to control which tools are exposed to the LLM. Each tier groups related tools by domain. This matters because LLMs have context windows — exposing 220 tool definitions consumes tokens. For simple tasks, 72 core tools is plenty. For complex automation, enable everything with --caps all.
| 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 |
Tier details¶
Core (72 tools, always on)¶
The foundation. Covers session management, navigation, screenshots, PDF generation, page scraping, JavaScript evaluation, DOM manipulation, user input (click, type, fill, hover, drag, key press), cookies, tab management, iframe interactions, shadow DOM piercing, event subscription, and natural language interaction (find-by-text, NL click/fill). These tools are always available regardless of --caps settings.
Network (20 tools)¶
Control over HTTP traffic. Set custom headers, override User-Agent, block requests by URL pattern, throttle network speed, disable cache, capture HAR files, intercept and modify requests in-flight, mock responses, modify responses in-flight, get request/response bodies, replay HAR files, and list all network requests made by the page. Essential for testing API interactions, simulating slow connections, and debugging network issues.
Storage (18 tools)¶
Read and write browser storage. Full localStorage and sessionStorage CRUD, Cache Storage listing/entries/deletion, IndexedDB listing/data retrieval/clearing, and storage state save/restore (exports cookies + all storage as JSON for later restoration). Useful for preserving authentication state between sessions or testing storage-dependent features.
Emulation (9 tools)¶
Simulate devices and environments. Emulate specific devices (iPhone 15, Pixel 8, etc.) with correct viewport, user agent, and touch events. Override geolocation, timezone, dark mode, locale, CPU throttling, and sensor values (accelerometer, gyroscope). Essential for responsive testing and geo-dependent features.
A11y (4 tools)¶
Accessibility tree inspection. Capture the full accessibility tree with LLM-friendly element references (e.g., el-1, el-2) that can be passed to other tools. Get specific nodes by ID, traverse ancestors, and run axe-core accessibility audits. The foundation for wavexis_act (natural language interaction).
Interactions (5 tools)¶
Handle browser-level interactions that aren't DOM clicks. Accept/dismiss JavaScript dialogs (alert, confirm, prompt), intercept file downloads, grant browser permissions (geolocation, notifications, camera, microphone), and reset permissions. Essential for testing pages with popups or permission flows.
DevTools (31 tools)¶
Chrome DevTools protocol exposed as tools. Performance metrics (LCP, FCP, CLS, TTFB), CPU profiling, heap snapshots, JS/CSS coverage, combined trace+perf, CSS style inspection, JavaScript debugging (breakpoints, step over/into/out, pause/resume), event listener inspection, element highlighting, console capture, browser logs, security state, window bounds control, and annotated screenshots with element labels. The most powerful tier for debugging and optimization.
Vision (7 tools)¶
Pixel-precise mouse control. Move, press, release, click, and double-click at specific x,y coordinates. Unlike DOM-based clicks (which use CSS selectors), vision tools operate on raw screen coordinates. Useful when elements don't have stable selectors or when interacting with canvas/WebGL.
Video (4 tools)¶
Browser video recording. Start/stop recording, add chapter markers at specific timestamps, and overlay action labels on the video. Recordings capture the full page including animations and interactions. Useful for bug reports, demos, and regression testing.
Testing (6 tools)¶
Assertion-based testing. Assert element visibility, text presence, and URL matching. Generate robust CSS selectors for elements (tries ID, data-testid, class, nth-child). These tools return pass/fail results as JSON, making them ideal for automated test pipelines.
Workflows (6 tools)¶
Advanced automation. Execute multi-action YAML sequences in a single tool call (navigate → wait → click → fill → screenshot). Send raw CDP or BiDi commands as an escape hatch for any browser feature not covered by a dedicated tool. Create, list, and close isolated browser contexts for parallel sessions.
Data (7 tools)¶
Data extraction and analysis. Record browser actions to YAML (codegen for test generation), run Lighthouse audits (performance, accessibility, SEO, best-practices), extract structured data via CSS selectors, intercept WebSocket messages, crawl multiple URLs with depth control, compare screenshots for visual regression testing, and measure Core Web Vitals (LCP, CLS, INP) with ratings and score.
Experimental (31 tools)¶
Niche and experimental features. Service worker management (list, unregister, update, emulate), animation control (list, pause, play, set rate), WebAuthn virtual authenticators, WebAudio context inspection, media player monitoring, Cast (Chromecast) control, Bluetooth emulation (adapter, device connect/disconnect/list), browser extension management (install, uninstall, list), and browser preference get/set. These tools cover edge cases that most users won't need but are invaluable when they do.
--caps flag¶
# Core only (default, 72 tools)
wavexis-mcp
# All tiers (220 tools)
wavexis-mcp --caps all
# Specific tiers
wavexis-mcp --caps network,storage,emulation
# Core + specific tiers (core is always included)
wavexis-mcp --caps core,devtools,a11y
# Equals syntax
wavexis-mcp --caps=devtools,a11y
Choosing tiers
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. Use all only when you need maximum capability.
CLI flags¶
| Flag | Default | Description |
|---|---|---|
--transport |
stdio |
Transport mode: stdio (for LLM clients) or http (for CI/CD, Docker) |
--host |
127.0.0.1 |
HTTP bind host (only used with --transport http) |
--port |
8765 |
HTTP listen port (only used with --transport http) |
--allow-remote |
false |
Bind HTTP to 0.0.0.0 (enables remote access — use behind a reverse proxy!) |
--caps |
core |
Comma-separated capability tiers to enable |
--rate-limit |
60 |
Max tool calls per second per session (token bucket) |
--rate-burst |
10 |
Max burst size for rate limiting |
--blocked-origins |
(empty) | Comma-separated URL patterns to block on every new session (e.g. *.ads.example.com,*tracker*) |
--storage-state |
(unset) | Path to a JSON file with cookies/localStorage/sessionStorage to restore on every new session |
--auto-web-vitals |
false |
Inject web-vitals collection script (LCP, CLS, INP) after every navigation |
--help |
— | Show help and exit |
Environment variables¶
| Variable | Default | Description |
|---|---|---|
WAVEXIS_BROWSER_PATH |
auto-detect | Path to Chrome/Edge binary. If not set, WaveXisMCP auto-detects Chrome then Edge. |
WAVEXIS_BACKEND |
cdp |
Default backend: cdp (recommended for Chrome/Edge) or bidi (cross-browser, supports Firefox). Can be overridden per session. |
WAVEXIS_MCP_OUTPUT_DIR |
current directory | Base directory for file outputs (screenshots, PDFs, traces, etc.). All output_path parameters are resolved relative to this directory. Paths that escape this base are rejected. |
WAVEXIS_MCP_ALLOW_INTERNAL_URLS |
unset | Set to 1 to allow navigation to private/internal IP addresses (e.g., localhost, 10.x.x.x, 192.168.x.x). By default, internal URLs are blocked to prevent SSRF. Useful for testing local development servers. |
WAVEXIS_MCP_ALLOW_RAW_COMMANDS |
unset | Set to all to allow arbitrary CDP/BiDi commands via wavexis_raw_cdp and wavexis_raw_bidi. By default, only a read-only allowlist of safe commands is permitted. |
Browser selection (BiDi)¶
The BiDi backend supports both Chrome and Firefox. Use the browser parameter when opening a session:
# Chrome (default) — auto-launches chromedriver from PATH
wavexis_session_open(backend="bidi", browser="chrome")
# Firefox — auto-launches geckodriver from PATH
wavexis_session_open(backend="bidi", browser="firefox")
If chromedriver or geckodriver is not in PATH, the backend returns a clear error with installation instructions. When a driver is already running on the default port (9222 for Chrome, 4444 for Firefox), the backend connects to it instead of launching a new one.
Connect to existing Chrome¶
The connect_existing flag launches Chrome with --remote-debugging-port and connects to it via CDP. This is useful for reusing a browser profile with logged-in sessions:
# Launch Chrome with debug port (temp profile)
wavexis_session_open(connect_existing=true)
# Reuse an existing Chrome profile
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. If browser_url is also set, connect_existing is ignored and the provided URL is used directly.
Browser auto-detection¶
WaveXisMCP searches for Chrome/Edge in standard install locations:
- Windows:
C:\Program Files\Google\Chrome\Application\chrome.exe,C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe - macOS:
/Applications/Google Chrome.app/Contents/MacOS/Google Chrome,/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge - Linux:
/usr/bin/google-chrome,/usr/bin/chromium,/usr/bin/microsoft-edge
If your browser is in a non-standard location, set WAVEXIS_BROWSER_PATH:
Transport modes¶
stdio (default)¶
Used by LLM clients (Claude Desktop, Cursor, Windsurf, VS Code). The client launches WaveXisMCP as a subprocess and communicates over stdin/stdout. No network port needed.
HTTP¶
Used for CI/CD pipelines, shared instances, and Docker deployment. Runs as an HTTP server with SSE (Server-Sent Events) transport.
See HTTP Transport for details.