Skip to main content
Glama
README.md
# tauri-mcp

A generic [MCP](https://modelcontextprotocol.io) server that drives a **built
Tauri app's UI over WebDriver** (tauri-driver + msedgedriver on Windows /
WebKitWebDriver on Linux): launch the real app, then click, type, scroll, drag,
read, and screenshot it like a human — or drop to raw JS when needed.

Not tied to any one project. Point it at any local Tauri app with `projectDir`
or `appPath`. This server only knows how to drive a window; anything
app-specific (reading an app's own database or config) belongs in a separate
server of your own.

## Tools

All tools are prefixed `app_` and operate on a single running session (one app
at a time).

### Session

| Tool | What it does |
| --- | --- |
| `app_launch` | Launch a built Tauri app under WebDriver. `projectDir` (or `appPath`) picks which app; `TAURI_PROJECT_DIR` is the fallback. Optional `args`, `env` (extra environment variables) and `renderTimeoutMs`. The app starts in its own folder, so relative paths resolve there. Hard-errors if the window never renders (see Troubleshooting). |
| `app_attach` | Attach to an app that is already running with a WebView2 remote-debugging port (Windows) instead of launching a new copy. |
| `app_close` | Close the session and stop tauri-driver, or detach after `app_attach`. Reports `appWasRunning`, so a crash before close is visible. |
| `app_status` | Whether a session is running, and if so the binary + driver port. |
| `app_force_cleanup` | Close only this server's app session and drivers; unrelated processes remain untouched. |
| `app_window` | Resize / move / maximize / minimize / fullscreen the window; reports resulting size+position. |
| `app_reload` | Reload the webview (resets front-end state; backend process keeps its state). |

### Acting (mouse / keyboard)

| Tool | What it does |
| --- | --- |
| `app_click` | Click by CSS `selector` **or** `text` (visible text / accessible name). `button` left/right/middle, `count` 2 for double-click. |
| `app_click_at` | Left/right/middle click at raw x,y viewport coordinates (canvas / native-drawn UI). |
| `app_scroll` | Mouse-wheel scroll by a pixel delta (+down/-up, +right/-left); optional `selector` to scroll a specific pane. |
| `app_type` | Type `value` into an input/textarea found by `selector` or `text` (placeholder/label); optional Enter. |
| `app_press_key` | Raw keyboard: any key — literal chars, F1-F12, arrows, Home/End/PageUp/Down, and modifier chords (Ctrl+A, Ctrl+Shift+K). |
| `app_hover` | Hover an element (by selector or text) to trigger tooltips / hover menus. |
| `app_select` | Pick an option from a native `<select>` by `optionText`/`optionValue`/`optionIndex`. |
| `app_drag` | Drag an element onto another (`to`) or by a pixel `offset` — sliders, range inputs, reordering, canvas handles. |

### Reading / observing

| Tool | What it does |
| --- | --- |
| `app_snapshot` | Title + visible text + every visible interactive element (role, text, selector). The "what can I act on" view. |
| `app_read` | One element's live state: text, current input value (DOM property, reflects controlled React inputs), tag, displayed/enabled, optional attribute. |
| `app_wait_for` | Poll until a selector/text appears or disappears — for async loading, toasts, dialogs. |
| `app_console_logs` | Browser console output (`log`/`warn`/`error` + uncaught exceptions) since launch. |
| `app_screenshot` | PNG screenshot of the window, or of a single element (selector/text) for focused visual diffing. |
| `app_wait_for_js` | Poll a JS function body until it returns something truthy: for canvas scenes, stores or backend state with no DOM text. |
| `app_record` | Frame timing over a duration (fps, p50/p95/max, stalls over 50 ms), optionally sampling a JS expression every frame. |
| `app_logs` | Tail a log/trace file, or the stdout/stderr captured from the driver and app since launch. |
| `app_desktop_screenshot` | Screenshot a desktop region or another program's window in physical pixels (Windows). |
| `app_dialogs` / `app_dialog_click` | List the app's Win32 message boxes (title, text, buttons) and press a button by name (Windows). |
| `app_list_windows` / `app_switch_window` | List windows (handle, title, URL) and switch the active one. |

Every tool that acts on one webview also takes an optional `window`: a handle, or a substring of
the window's title or URL (e.g. `"#settings"`). The call runs there and the active window is left
unchanged, so multi-window apps do not need `app_switch_window` round trips.

### Escape hatch

| Tool | What it does |
| --- | --- |
| `app_execute_js` | Run arbitrary JavaScript in the window and return the result. |

`app_execute_js` is unrestricted: it can read/write any DOM or JS state and
invoke **any** Tauri backend command directly via
`await window.__TAURI_INTERNALS__.invoke("cmd_name", { arg })` (always present
in Tauri v2, regardless of `withGlobalTauri`) — anything the app's own frontend
can do, including commands with real side effects (writing config, filesystem,
launching processes). No sandboxing beyond what the app's own command handlers
enforce. It's also the **workaround for OS-native dialogs** (see below).

## Targeting elements: prefer `text`

`app_snapshot` emits positional CSS selectors like
`div > div:nth-of-type(3) > button`, which break the moment the DOM is
restructured. Wherever a tool takes a target, prefer `text` (visible text or
accessible name) — `app_click({ text: "Browse" })` is how a human would say it
and survives layout changes. `exact: true` requires an exact match; otherwise
it tries exact text, then substring, then ARIA accessible name (covers
icon-only buttons with `aria-label`).

## Requirements

- Node 24+ and `npm install` once in this folder.
- [`tauri-driver`](https://v2.tauri.app/develop/tests/webdriver/): `cargo install tauri-driver --locked`.
- Windows: Microsoft Edge WebDriver **version-matched to your installed
  WebView2 Runtime** (Settings → About Microsoft Edge WebView2, or
  `HKLM\SOFTWARE\WOW6432Node\Microsoft\EdgeUpdate\Clients\{F3017226-FE2A-4295-8BDF-00C3A9A7E4C5}`
  → `pv`). A mismatched major version connects fine but silently never leaves
  `about:blank` — `app_launch` now detects this and errors. `winget install
  Microsoft.EdgeDriver` does **not** reliably match; download the exact version
  from `https://msedgedriver.microsoft.com/<version>/edgedriver_win64.zip` and
  drop it at `./bin/msedgedriver.exe` (checked first) or set `EDGEDRIVER_PATH`.
- Windows apps with embedded `requireAdministrator` manifest trigger UAC on
  `app_launch`. Approve prompt at desktop; elevated helper runs `tauri-driver`,
  WebDriver, and app at same integrity level. Helper owns private Windows job
  with kill-on-close; `app_close` tears down only this session. Never weaken
  production manifest for automation.
- The target app must already be built, **and not with plain `cargo build`** — a
  debug binary points at `devUrl` and only renders if a Vite dev server is up.
  Use `cargo tauri build --debug --no-bundle` (fast) or `cargo tauri build
  --no-bundle` (release). `app_launch` does not build for you.

When `projectDir`/`appPath` is omitted, `app_launch` uses the `TAURI_PROJECT_DIR`
environment variable; if that is unset too, it returns a clear error. There is
no built-in default project.

## Run / verify

```bash
npm install
# point it at any built Tauri app:
TAURI_PROJECT_DIR=/path/to/tauri-project npm run verify-automation
# or:
TAURI_APP_PATH=/path/to/built/app npm run verify-automation
```

The verify script launches the app, snapshots it, clicks the first interactive
element, screenshots, and closes.

## Testing without touching real user data

Point the app at a throwaway data folder when it supports one, for example
`app_launch({ projectDir, args: ["--data-dir=C:/temp/test-profile"] })`, and pass any
diagnostics switches through `env`, e.g. `env: { "MY_APP_TRACE": "C:/temp/trace.log" }`, then
read them back with `app_logs({ path: "C:/temp/trace.log" })`.

On Windows each argument must be a single `--name` or `--name=value` switch. msedgedriver treats
app arguments as browser switches: it prefixes bare values with `--`, lowercases and reorders them,
so `--data-dir C:/x` arrives as `--c:/x --data-dir`. `app_launch` rejects bare values up front.

## Attaching to a running app

Start the app yourself with a debugging port, then attach:

```powershell
$env:WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS = "--remote-debugging-port=9333"
& "C:/path/to/app.exe"
```

`app_attach({ debugPort: 9333, appPath: "C:/path/to/app.exe" })`. WebView2 ignores new
arguments when another instance already shares the same user-data folder, so close other copies
first. `app_close` detaches and leaves the app running.

## OS-native dialogs

WebDriver can only see the webview DOM. On Windows, `app_dialogs` lists the app's message boxes
and `app_dialog_click({ button: "OK" })` presses one, which unblocks launches that stall behind
a startup warning. File/folder pickers are not message boxes and remain out of reach. Workaround
for those: skip the dialog and drive the backend directly with `app_execute_js`, e.g.

```js
// instead of clicking a "Choose folder" button that opens a native picker:
return await window.__TAURI_INTERNALS__.invoke("set_output_dir", { path: "/some/folder" });
```

## Troubleshooting

- **`app_launch` errors "window never rendered"** — msedgedriver/WebView2
  version mismatch, or a plain `cargo build` binary. See Requirements.
- **"a session is already running"** — `app_force_cleanup` closes only session
  owned by this MCP server; it cannot recover drivers from a prior crashed server.
- **Selectors keep breaking** — target by `text` instead (see above).

## Register with Claude Code

Add it to an `.mcp.json` (project root, or `~/.claude.json` for all projects),
then restart Claude Code. Tools then appear as `tauri:app_launch`, etc.

```json
{
  "mcpServers": {
    "tauri": {
      "command": "node",
      "args": ["--no-warnings", "/absolute/path/to/tauri-mcp/index.mjs"]
    }
  }
}
```

Or via the CLI:

```bash
claude mcp add tauri -- node --no-warnings /absolute/path/to/tauri-mcp/index.mjs
```

TDQS

A4.2/5.0

Scored across 22 tools

Disambiguation5/5

Each tool has a clearly distinct purpose, from app_click (element click) to app_click_at (coordinate click), app_type (input typing), app_read (single element state), and app_snapshot (full window state). No two tools serve overlapping roles.

Naming Consistency5/5

All tools follow the consistent pattern 'app_verb_noun' in snake_case (e.g., app_list_windows, app_execute_js, app_force_cleanup). No mixing of conventions or chaotic naming.

Tool Count5/5

With 22 tools, the set is well-scoped for automating Tauri desktop apps, covering launching, interaction, state inspection, window management, and debugging without being bloated.

Completeness5/5

The toolset covers the full lifecycle (launch/close), all major user interactions (click, type, scroll, drag, select, hover), state reading (read, snapshot, console logs), window management, and debugging (execute_js, force_cleanup). No obvious gaps for typical UI automation.