Victauri MCP server

---

Testing Tauri apps today means choosing between frontend mocks that lie about your backend, WebDriver setups that take a weekend, or paying for macOS CI runners. Victauri replaces all three: it embeds a lightweight server inside your Tauri process (debug builds only) that gives your test suite, curl, and CI direct access to the DOM, IPC layer, Rust backend state, the database, and native windows — from one test, on all three platforms. No WebDriver. No browser dependency. Works on macOS, Windows, and Linux.

That same server also speaks MCP, so any AI agent — Claude Code, Cursor, Windsurf — can drive and debug your app with the exact same full-stack access. Testing is the job; the agent integration is the bonus.

Tested against real-world Tauri apps. In a one-time deep evaluation (May 2026) across 5 open-source apps (Kanri, En Croissant, Surrealist, Duckling, Lettura), 867 / 895 checks passed (96.9%) with zero Victauri bugs and zero changes to the apps. A reproducible compat harness (scripts/compat) re-runs an app-agnostic smoke battery against the current code on demand (and weekly), pinned to three Tauri-2 apps (Kanri, En Croissant, Lettura). It is a best-effort net for upstream drift, not a release gate — third-party apps move on their own schedules and periodically need re-pinning. See the compat README for what it covers and current per-app status.

Note — browser mode removed (2026-06-09). The experimental victauri-browser extension + @4da/victauri-browser npm package (MCP for any website) have been removed so Victauri can focus on its strength: full-stack introspection inside Tauri apps. For browser automation, use Playwright or the Chrome DevTools Protocol. The Tauri plugin is unaffected. Details & migration: #15.

What You Get

For your test suite and CI:

• Full-stack verification — click a button, verify the IPC call, query the database to confirm the write, check the UI updated — in one test
• Direct backend access — query SQLite databases, browse app files, read config, inspect process memory — no webview proxy
• Ghost command detection — find high-confidence orphaned frontend calls (confirmed_ghosts: invoked but only ever errored "not found"), and backend commands the frontend never calls
• Cross-boundary state checking — compare DOM state against Rust backend state and catch the drift between them
• Time-travel recording — record interactions, checkpoint state, replay sequences, generate test files
• Cross-platform, no WebDriver — the same tool surface on macOS, Windows, and Linux (no CDP dependency); runs headless in CI under xvfb. Platform limits are documented, not hidden: trusted (OS-level) input is Windows-only (other platforms fall back to synthetic events), and window screenshots need X11/XWayland on Linux (pure Wayland fails with a clear error)
• Zero runtime cost in release — the server is gated behind #[cfg(debug_assertions)], so init() is a no-op and nothing listens in release builds. Add victauri-plugin as a normal [dependencies] entry (the app binary cannot see [dev-dependencies]); the crate still compiles in, so to keep it out of release binaries entirely make it an optional dependency behind a Cargo feature (victauri init --optional scaffolds it). SQLite note: the default bundled-sqlite feature turns on rusqlite/bundled, and Cargo feature unification applies it to your app's rusqlite too, in release builds as well. If your app links a system SQLite or SQLCipher, use default-features = false, features = ["sqlite"]

Bonus — for AI agents: the same server speaks MCP, so Claude Code, Cursor, Windsurf, and any MCP client get this full-stack access for interactive debugging — no extra setup.

Will Victauri work on your app?

Victauri is a development-time dependency you add to your own app's source and rebuild (a normal [dependencies] entry — not [dev-dependencies], which the app binary cannot use) — not a tool you attach to an already-running or shipped app. It works when all four hold:

1. Tauri 2, or a Tauri 3 pre-release (turn on victauri-plugin's tauri-v3 feature — see the plugin README). Tauri 1.x apps can't host it — their webkit2gtk-sys 0.18 and Victauri's 2.x both link the native web_kit2 library, an unresolvable cargo conflict. (Tauri 2 is the current major; Tauri 1 is legacy.)
2. Built from source with the plugin wired in — one line in Cargo.toml, .plugin(victauri_plugin::init()), and the victauri:default permission (a capability file, or the runtime grant victauri init --optional generates). There is no inject-into-a-foreign-binary path.
3. A debug build. The server is #[cfg(debug_assertions)]-gated, so init() is a no-op and nothing listens in release. It's a dev/test-time tool by design.
4. Each window grants victauri:default. Tauri's per-window permission ACL silently blinds the bridge without it; the window introspectability tool detects and explains this.

Framework does not matter, because the bridge works at DOM level: it has been run on React, Vue/Nuxt and vanilla apps (what was actually run). Nor does the OS/webview engine: WebView2, WKWebView and WebKitGTK are all exercised in CI.

✅ Works on	❌ Won't work on
Your own Tauri 2 (or Tauri 3 pre-release) app during development	Tauri 1.x apps
Any Tauri 2/3 app you can build from source (debug)	Release / production builds
Any frontend framework, any of the 3 OSes	A binary you didn't build (no source)
	Non-Tauri apps (Electron, native, plain web)

Full details, edge cases, and a tested-apps list: Compatibility.

Quick Start

Install the CLI

cargo install victauri-cli

Set up your project

From your Tauri project root:

victauri init

This will:

• Add victauri-plugin and victauri-core (dev: victauri-test, tokio) to your Cargo.toml
• Add .plugin(victauri_plugin::init()) to your Tauri builder when it finds one
• Create capabilities/victauri.json (grants victauri:default), .mcp.json, starter tests in tests/, a CI workflow, a CLAUDE.md block and a Claude Code skill (.claude/skills/victauri/SKILL.md)
• Print any steps it could not do itself

Wire the plugin

Skip this if init reported that it patched your builder. Otherwise add one line:

// src-tauri/src/main.rs (or lib.rs)
tauri::Builder::default()
    .plugin(victauri_plugin::init())
    .invoke_handler(tauri::generate_handler![/* your commands */])
    .run(tauri::generate_context!())
    .expect("error while running tauri application");

In release builds, init() returns a no-op plugin: the server never starts and the linker strips it, so no feature flags are needed. #[inspectable] likewise compiles none of its metadata (descriptions, intents, examples) into a release build. The plugin's dependencies are still compiled (see below).

Zero release footprint. As an ordinary dependency the crate still compiles into a release build (inert; the linker drops the unreachable server, but the default bundled-sqlite feature adds SQLite's C code — about +1.7 MB without LTO, ~58 KB with LTO in a fresh project — and also switches your app's own rusqlite, if any, to bundled). victauri init --optional instead scaffolds Victauri as an optional dependency behind a victauri Cargo feature, so release builds contain none of it; you then start the app with the feature on (npm run tauri dev -- --features victauri, or pnpm tauri dev --features victauri). See Getting Started → Zero release footprint.

Run tests

Start your app, then run the smoke suite:

npm run tauri dev                                # start your app (or pnpm/yarn/bun tauri dev)
cd src-tauri && VICTAURI_E2E=1 cargo test --test smoke -- --test-threads=1   # in a second terminal; tests share one app

On Windows the running app locks its .exe, and cargo test rebuilds it, so give the test run its own target directory: CARGO_TARGET_DIR=target-test VICTAURI_E2E=1 cargo test --test smoke -- --test-threads=1.

Or use the CLI for instant validation:

victauri test                                    # 11 built-in smoke checks
victauri check                                   # server health + IPC diagnostics
victauri call dom_snapshot                       # any tool from the shell → JSON on stdout

Use with your agent

One command per client. Each writes (or merges into) that client's MCP config, pointing at victauri bridge --app <your identifier>, plus agent instructions telling it to prefer Victauri over CDP/Playwright, verify it reached the right app, and await async work with wait_for:

Client	Command	Writes
Claude Code	victauri setup claude (also what plain victauri init does)	.mcp.json, CLAUDE.md block, .claude/skills/victauri/SKILL.md
Cursor	victauri setup cursor	.cursor/mcp.json, AGENTS.md block
VS Code / GitHub Copilot	victauri setup vscode	.vscode/mcp.json, AGENTS.md block
Windsurf / Devin Desktop	victauri setup windsurf --user-config	user-level mcp_config.json (the only config it documents), AGENTS.md block
OpenAI Codex	victauri setup codex	.codex/config.toml (trusted projects; --user-config for ~/.codex), AGENTS.md block
Gemini CLI	victauri setup gemini	.gemini/settings.json, AGENTS.md block, GEMINI.md import
Zed	victauri setup zed	.zed/settings.json, AGENTS.md block (Zed reads only the first rules file it finds — a .rules / .cursorrules hides AGENTS.md)
Roo Code	victauri setup roo	.roo/mcp.json, AGENTS.md block
All of the above	victauri setup all	every project-level file above

Existing configs are merged, never overwritten (comments in JSONC files survive), re-running changes nothing, and --dry-run shows what would change. See how Victauri compares to other Tauri agent and test tools.

Connect an AI agent by hand

Add .mcp.json to your project root (created automatically by victauri init):

{
  "mcpServers": {
    "victauri": {
      "command": "victauri",
      "args": ["bridge"]
    }
  }
}

The victauri bridge stdio proxy discovers the running app's port at connect time and re-discovers on restart, so the agent always reaches the right app — even across rebuilds, or when several Victauri apps are running (add "--app", "<your.bundle.identifier>" to pin one). Prefer it over a fixed "url": "http://127.0.0.1:7373/mcp", which hardcodes a port and can bind the wrong app.

Works with Claude Code, Cursor, Windsurf, and any MCP client. Your agent gets full-stack access: DOM snapshots, IPC monitoring, command invocation, screenshot capture, accessibility auditing, and more.

With Claude Code, start your app and Claude can immediately:

• Inspect the DOM tree and click/type/fill any element
• Invoke any #[tauri::command] and verify the response
• Read app config, list files, query SQLite databases
• Take screenshots and audit accessibility
• Record interactions and replay them as tests

---

Writing Tests

The e2e_test! macro connects for you, and skips the test (printing a skip line) unless VICTAURI_E2E is set. It does not detect a server, so set the variable where a run must count:

use victauri_test::{e2e_test, VictauriClient};

e2e_test!(greet_flow, |client| async move {
    client.fill_by_id("name-input", "World").await.unwrap();
    client.click_by_id("greet-btn").await.unwrap();
    client.expect_text("Hello, World!").await.unwrap();
});

Locator API

For complex queries, composable locators with auto-waiting expectations:

use victauri_test::prelude::*;

e2e_test!(settings_flow, |client| async move {
    let save = Locator::role("button").and_text("Save");
    let email = Locator::label("Email address");

    email.fill(&mut client, "user@example.com").await.unwrap();
    save.click(&mut client).await.unwrap();

    Locator::test_id("toast-message")
        .expect(&mut client)
        .to_contain_text("Settings saved")
        .await
        .unwrap();
});

Locators support role, text, test_id, css, label, placeholder, alt_text, and title strategies with chainable refinement (.and_text(), .nth(), .and_tag()). See the Testing Guide for the full Locator API reference.

Direct Client Methods

Method	What it does
click_by_text("Submit")	Find element by visible text, click it
click_by_id("save-btn")	Find element by HTML id, click it
fill_by_id("email", "a@b.com")	Find input by id, fill value
type_by_id("search", "query")	Find input by id, type char-by-char
select_by_id("theme", "dark")	Find select by id, choose option
expect_text("Success!")	Poll until text appears (5s timeout)
expect_no_text("Error")	Poll until text disappears (3s timeout)
text_by_id("counter")	Get text content of element by id

---

Full-Stack Verification

This is what sets Victauri apart — verifying that frontend actions actually trigger the right backend logic.

UI to IPC to Database

// Click "Save" in the UI
client.click_by_id("save-btn").await?;

// Verify the IPC command was called
let log = client.get_ipc_log(None).await?;
assert_ipc_called(&log, "save_settings");

// Verify the database was actually written
let result = client.query_db(
    "SELECT value FROM settings WHERE key = 'theme'",
    None, None,
).await?;
assert_eq!(result["rows"][0]["value"], "dark");

Fluent Verification

Check multiple conditions at once — DOM, IPC, accessibility, errors — with a single report:

client.verify()
    .has_text("Settings saved")
    .ipc_was_called("save_settings")
    .no_console_errors()
    .no_ghost_commands()
    .ipc_healthy()
    .coverage_above(80.0)
    .run()
    .await?
    .assert_all_passed();

Ghost Command Detection

Find orphaned commands — called in the frontend but missing from the backend:

let ghosts = client.detect_ghost_commands().await?;
assert!(ghosts["confirmed_ghosts"].as_array().unwrap().is_empty(),
    "Found ghost commands: {ghosts}");

See the Testing Guide for IPC checkpoints, visual regression testing, IPC coverage, accessibility auditing, performance monitoring, time-travel recording, CI integration, and more.

---

MCP Tools

35 tools across the full stack — backend, IPC, webview, and introspection:

Backend tools (direct Rust access, no webview needed)

Tool	What it does
app_info	App config, directory paths, env vars, discovered databases, process info
list_app_dir	Browse files in app data/config/log/local_data directories
read_app_file	Read files from app backend directories (UTF-8 or base64)
query_db	Read-only SQLite queries with auto-discovery
invoke_command	Call any Tauri command through the app's real IPC path (dispatched via the webview's invoke, so it needs a live window)
app_state	Read app-defined backend-state probes (pipeline/queue/cache internals) — no IPC round-trip
get_memory_stats	Real-time OS process memory (working set, page faults)

IPC tools

Tool	What it does
get_registry	List all #[inspectable] command schemas
detect_ghost_commands	Find orphaned frontend IPC calls (high-confidence confirmed_ghosts)
check_ipc_integrity	Detect stuck/stale/errored IPC calls
verify_state	Compare frontend DOM against backend state
resolve_command	Natural language to matching Tauri command

Webview tools

Tool	What it does
eval_js	Execute JavaScript in the webview
dom_snapshot	Full accessibility tree with ref handles
find_elements	Search by text, role, test ID, CSS, label, placeholder, alt, title
screenshot	Platform-native window capture (no Chromium)
wait_for	Poll for conditions: text, selector, IPC settle, JS expression, Tauri event, or a backend log line — await async backend work without sleeps
assert_semantic	Evaluate JS + assert against expected value

Compound tools (multiple actions per tool)

Tool	Actions
interact	click, double_click, hover, focus, scroll_into_view, select_option
input	fill, type_text, press_key (keyboard combos supported; trusted: true = OS-level input, Windows only)
window	get_state, list, manage, resize, move_to, set_title, introspectability
storage	get, set, delete, get_cookies
navigate	go_to, go_back, get_history, set_dialog_response, get_dialog_log
recording	start, stop, checkpoint, list_checkpoints, get_events, events_between, get_replay, export, import, replay, flush
inspect	get_styles, get_bounding_boxes, highlight, clear_highlights, audit_accessibility, get_performance
css	inject, remove
route	add (block / fulfill / delay fetch+XHR), list, clear, clear_all, matches
trace	start, stop, status, frames (background screencast ring buffer)
animation	list, scrub, sample (Web Animations API — no CDP)
logs	console, network, ipc, navigation, dialogs, events, slow_ipc, clear; the Rust backend: backend, backend_digest, stdout (Backend Logs)
introspect	command_timings, coverage, command_catalog, contract_record, contract_check, contract_list, contract_clear, startup_timing, capabilities, db_health, plugin_state, processes, plugin_tasks, event_bus, event_bus_clear
fault	inject (delay/error/drop/corrupt), list, clear, clear_all
explain	summary, last_action, diff
get_plugin_info	Plugin config: port, tools, privacy, version
get_diagnostics	Shadow DOM, service workers, iframes, large DOM detection

No MCP client needed: every tool is also a shell command — victauri call query_db query="SELECT 1" prints the result as JSON (victauri tools <name> shows a tool's arguments) — and a REST endpoint, POST /api/tools/{name}. See the Tools Reference.

---

How It Works

AI Agent / cargo test / curl
        |
        v
  HTTP on :7373
  ├── /mcp          (MCP protocol — for AI agents)
  ├── /api/tools    (REST API — for scripts and CI)
  └── /health       (health check — for monitoring)
        |
        v
  Victauri Plugin  (inside Tauri process)
     |       |       |
     v       v       v
  WebView  IPC    Backend
  - DOM    - log   - app config
  - click  - args  - file system
  - eval   - cmds  - SQLite DBs
  - a11y   - ghost - memory
  - perf   - verify- env vars

Victauri runs inside the Tauri process — same thread pool, same memory space. This isn't an implementation detail; it changes what's possible:

	Embedded (Victauri)	External process
Tool response	Backend tools: one localhost HTTP hop plus an in-process call (no extra process). Webview tools: about 10-30 ms JS round trip	Same HTTP hop, plus a relay through a separate process
State accuracy	Backend state read live from the process. Webview-side logs (IPC, console) are bounded page buffers	Whatever the external tool can observe
Backend access	Full (AppHandle, DB, state)	Limited (webview only)
Setup	One line in Cargo.toml	Separate process + config
Release build	init() is a no-op (zero runtime cost)	Must be disabled manually

Port selection: Victauri tries port 7373 first, then falls back through 7374-7383 if taken, and if that whole range is unavailable (on Windows, Hyper-V/WSL reserve dynamic port blocks that can cover it) it listens on a port the OS assigns. The actual port is written to a temp directory for automatic client discovery. VICTAURI_PORT (or VictauriBuilder::port) changes the preferred port.

---

Architecture

victauri/
├── crates/
│   ├── victauri-plugin/     # Tauri plugin + MCP server + JS bridge (the main crate)
│   ├── victauri-core/       # Shared types (events, registry, snapshots, verification)
│   ├── victauri-macros/     # #[inspectable] proc macro for command schemas
│   ├── victauri-test/       # Test client + Locator API + assertion helpers
│   ├── victauri-cli/        # CLI: init, check, test, record, watch, coverage
│   └── victauri-watchdog/   # Health-check sidecar for crash recovery
├── docs/                    # mdbook documentation site
└── examples/
    └── demo-app/            # Multi-window Tauri app with 25 instrumented commands

Crate	Purpose	Tauri dependency?
victauri-plugin	Embed in your app — MCP server + bridge	Yes
victauri-test	Use in your tests — client + assertions	No
victauri-cli	Install globally — scaffold + diagnose	No
victauri-macros	Use on commands — #[inspectable]	No
victauri-core	Shared types (usually not used directly)	No
victauri-watchdog	Run as sidecar for crash recovery	No

---