All tools
Every tool cua-driver serves over MCP on macOS, Linux and Windows, with its parameters.
Every tool cua-driver serves over MCP on macOS, Linux and Windows, with its parameters.
cua-driver mcp serves these tools over stdio. Every tool also runs from the shell as cua-driver <tool> '<json-args>' (or cua-driver call <tool> through the daemon), with the same code path. Where a tool's text or schema differs by platform, its entry has one tab per platform; the choice persists across pages.
On Windows and Linux, bare cua-driver mcp owns its runtime and stops it on stdin EOF. On macOS it proxies to the installed CuaDriver.app daemon so Accessibility and Screen Recording grants keep the app identity; --socket selects an explicit daemon endpoint on every platform. See the process model for the lifecycle.
These parameters have the same shape on macOS, Windows and Linux (composed from shared schema fragments and held together by a CI consistency gate).
| Parameter | Tools | Meaning |
|---|---|---|
session | every action and cursor tool | Optional public run label. Repeat it on every call of multi-call work; it is not sticky. Without it, the call uses the connection's private implicit session. A label is never caller identity or authorization. |
target | move_cursor, click, drag, scroll, type_text, press_key, hotkey | The preferred per-call target: {kind:"window", pid, window_id} or {kind:"desktop", display_id:"primary"}. Cannot be combined with the legacy scope, pid or window_id. |
delivery_mode | click, double_click, right_click, drag, scroll, type_text, press_key, hotkey | "background" (the default) acts without fronting or raising the target. "foreground" briefly fronts it, acts, and restores the previous front window: use it only after a background attempt reports it did not land. Omitted or unknown values fall back to "background". |
include_screenshot | get_window_state | Default true (tree and screenshot). false returns the tree only, for re-indexing before an element action. |
capture_mode | get_window_state | Deprecated and ignored; still accepted so older callers do not fail. |
modifier, button, element_token | pointer and element tools | Held modifier keys, the mouse button, and the element handle from the latest get_window_state row. Action tools refuse element_index and snapshot_id. |
The required sets are the same on every platform: click requires nothing, scroll requires direction, and zoom requires window_id plus x1, y1, x2, y2. Legacy flat calls still check pid: a window action needs it, a desktop action omits it.
The first stateful call on a connection creates its implicit lifecycle session; later unnamed calls on that connection share it. The session's idle TTL is five minutes. Closing the connection, end_session or the idle timeout run the same cleanup.
Each get_window_state read replaces the previous snapshot of that window and lists the replaced ids in invalidated_snapshot_ids; a token from a replaced snapshot is refused with stale_element_token, which names the current snapshots. Window-relative x, y and zoom need a screenshot read of that window in the same session first (screenshot_context_missing otherwise), so pass one session label to the read and the actions of a one-shot cua-driver call sequence.
A window action may omit window_id only when its pid owns exactly one eligible top-level window. With several, the driver sends no input and returns code: "ambiguous_window_target", effect: "refused" and the candidates; retry with an exact window_id from that result or from list_windows. A pid with no eligible window returns window_target_not_found.
click, double_click, right_click, drag, scroll, type_text, press_key, hotkey and set_value return these structured fields:
| Field | Type | Meaning |
|---|---|---|
path | string | The delivery rung that ran: ax, cgevent, cgevent_fg, key_events, key_events_fg, pixel, x11_atspi, x11_pixel, x11_pixel_fg or msaa. |
verified | boolean or absent | true: the effect was read back through accessibility. false: the action ran but is unconfirmed. Absent: the tool does not verify. |
effect | string | confirmed, unverifiable or suspected_noop. |
escalation | object or absent | Present when the driver recommends the next rung: {recommended: "px" | "foreground" | "page", reason}. |
get_window_state may return degraded: true with a degraded_reason when the accessibility walk found no actionable elements (bridge not up, not on the session bus, or a non-accessible surface). Treat elements: [] as incomplete then, and act by pixel on the screenshot in the same response.
List, launch, quit, front and arrange apps and windows. Reference.
| Tool | Description | Platforms |
|---|---|---|
list_apps | List macOS apps, both currently running and installed-but-not-running, with per-app state flags: - running: is a process for this app live? | macOS, Linux, Windows |
list_windows | List layer-0 top-level windows known to WindowServer, including off-screen ones (minimized, other Space, hidden). | macOS, Linux, Windows |
launch_app | Launch a macOS app in the background: the target does NOT come to the foreground. | macOS, Linux, Windows |
kill_app | Force-terminate a process by pid (kill -9 equivalent on macOS / Linux; taskkill /F equivalent on Windows). | macOS, Linux, Windows |
bring_to_front | Persistently activate an app and leave it in the foreground. | macOS, Linux, Windows |
set_window_frame | Set one exact top-level window's frame in the desktop-coordinate space reported by list_windows and verify the resulting geometry through an independent readback. | macOS, Linux, Windows |
invoke_menu | Resolve an exact application-menu path one live native level at a time and invoke its final item through accessibility APIs. | macOS, Linux, Windows |
debug_window_info | Diagnostic: dump everything cua-driver sees about a pid's top-level windows from the daemon's session perspective. | Windows |
Screenshots, accessibility trees, verification and visual regions of a window. Reference.
| Tool | Description | Platforms |
|---|---|---|
get_window_state | Snapshot a window: the accessibility tree plus a screenshot. | macOS, Linux, Windows |
get_accessibility_tree | Return a lightweight snapshot of the desktop: running regular apps and on-screen visible windows with their bounds, z-order, and owner pid. | macOS, Linux, Windows |
verify_state | Deterministically verify bounded predicates against one exact window. | macOS, Linux, Windows |
parse_visual_regions | Parse one immutable registered capture into model-neutral text and icon regions. | macOS, Linux, Windows |
The desktop, screen size, cursor position and zoomed crops. Reference.
| Tool | Description | Platforms |
|---|---|---|
get_desktop_state | Capture the full display. | macOS, Linux, Windows |
get_screen_size | Return the logical size of the main display in points plus its backing scale factor. | macOS, Linux, Windows |
get_cursor_position | Return the current mouse cursor position in screen points (origin top-left). | macOS, Linux, Windows |
zoom | Capture a cropped JPEG of a window region (x1,y1)–(x2,y2) in screenshot pixel coordinates, with 20% padding added on each side. | macOS, Linux, Windows |
Click by element or pixel. Reference.
| Tool | Description | Platforms |
|---|---|---|
click | Click a target pid. | macOS, Linux, Windows |
Double-click and right-click by element or pixel. Reference.
| Tool | Description | Platforms |
|---|---|---|
double_click | Double-click at (x, y) or on an AX element identified by element_token. | macOS, Linux, Windows |
right_click | Right-click against a target pid. | macOS, Linux, Windows |
Drag, scroll, move the pointer, and press or release buttons. Reference.
| Tool | Description | Platforms |
|---|---|---|
drag | Press-drag-release gesture from (from_x, from_y) to (to_x, to_y) in window-local screenshot pixels: the same space get_window_state returns. | macOS, Linux, Windows |
scroll | Scroll the target pid. | macOS, Linux, Windows |
move_cursor | Move a cursor to (x, y). | macOS, Linux, Windows |
mouse_button_down | Press and hold a mouse button at (x,y) via background X11 delivery. | Linux |
mouse_button_up | Release a previously-held mouse button via background X11 delivery. | Linux |
mouse_drag | Move a previously-held mouse button to a new point via background X11 delivery. | Linux |
parallel_mouse_drag | Run multiple mouse drag gestures concurrently via Linux MPX/XI2 virtual master pointers. | Linux |
Type text into a field or window. Reference.
| Tool | Description | Platforms |
|---|---|---|
type_text | Insert text via AXSetAttribute(kAXSelectedText) into the element given by element_token, or the pid's focused element. | macOS, Linux, Windows |
Press keys and keyboard shortcuts. Reference.
| Tool | Description | Platforms |
|---|---|---|
press_key | Press and release one key. | macOS, Linux, Windows |
hotkey | Press a key combination: e.g. | macOS, Linux, Windows |
Set element values and read or write the clipboard. Reference.
| Tool | Description | Platforms |
|---|---|---|
set_value | Set an element's value by element_token. | macOS, Linux, Windows |
clipboard_read | List available system clipboard types and optionally return privacy-sensitive plain text. | macOS, Linux, Windows |
clipboard_write | Replace the system clipboard with exactly one value: plain text, an image from an absolute local path, or a file URL from an absolute local path. | macOS, Linux, Windows |
Run several action tools in one call. Reference.
| Tool | Description | Platforms |
|---|---|---|
run_actions | The default way to act: run one or more action tools in ONE call, in order, stop at the first failure, and (with observe) get what changed in the same response. | macOS, Linux, Windows |
Read and act on web pages, and prepare and navigate browsers. Reference.
| Tool | Description | Platforms |
|---|---|---|
page | Legacy browser compatibility tool. | macOS, Linux, Windows |
get_browser_state | Read-only browser inspection. | macOS, Linux, Windows |
browser_prepare | Explicitly prepare an owned DevTools endpoint for a browser. | macOS, Linux, Windows |
browser_navigate | Navigate one tab of an exactly-bound browser target to a new URL (http/https/about only). | macOS, Linux, Windows |
Exact browser input over CDP: clicks, typing, pointer, dialogs, files and downloads. Reference.
| Tool | Description | Platforms |
|---|---|---|
browser_click | Click a page element (by ref) or viewport coordinates in an exactly-bound tab. | macOS, Linux, Windows |
browser_type | Type text into an exactly-bound tab via the Input domain. | macOS, Linux, Windows |
browser_pointer | Perform hover, right-click, double-click, scroll, or drag in an exactly-bound browser tab. | macOS, Linux, Windows |
browser_dialog | Inspect or resolve a page-owned JavaScript alert, confirm, prompt, or beforeunload dialog on one exactly-bound tab. | macOS, Linux, Windows |
browser_set_input_files | Assign one or more explicit absolute local files to an exact live <input type=file> ref through CDP. | macOS, Linux, Windows |
browser_download | Trigger one download through an exact live browser ref and save it inside an explicitly approved directory. | macOS, Linux, Windows |
Start, escalate, inspect and end lifecycle sessions. Reference.
| Tool | Description | Platforms |
|---|---|---|
start_session | Optionally create or return a lifecycle session before acting. | macOS, Linux, Windows |
escalate_session | Deprecated compatibility tool for legacy capture-scope sessions. | macOS, Linux, Windows |
get_session | Read content-free lifecycle, cursor, recording, and idle status for one session visible to this authenticated transport. | macOS, Linux, Windows |
list_sessions | List content-free lifecycle summaries attached to this authenticated transport lease. | macOS, Linux, Windows |
get_session_state | Deprecated compatibility alias that reads a live legacy session's capture policy. | macOS, Linux, Windows |
end_session | End one visible lifecycle session and run its cursor, recording, configuration, and other cleanup hooks exactly once. | macOS, Linux, Windows |
Show, animate and style the agent cursor. Reference.
| Tool | Description | Platforms |
|---|---|---|
set_agent_cursor_enabled | Show or hide the agent cursor owned by a session. | macOS, Linux, Windows |
set_agent_cursor_motion | Configure the movement style, timing, effects and visibility timing for a session cursor. | macOS, Linux, Windows |
set_agent_cursor_theme | Select an already-installed cursor theme for a session. | macOS, Linux, Windows |
get_agent_cursor_state | Return the session cursor's theme, semantic playback, position, visibility, and motion. | macOS, Linux, Windows |
Record and replay trajectories. Reference.
| Tool | Description | Platforms |
|---|---|---|
start_recording | Start trajectory recording for the calling session. | macOS, Linux, Windows |
stop_recording | Stop trajectory recording. | macOS, Linux, Windows |
get_recording_state | Report the current trajectory recorder state: whether recording is enabled, the output directory (when enabled), and the 1-based counter for the next turn folder that will be written. | macOS, Linux, Windows |
replay_trajectory | Replay a recorded trajectory by re-invoking every turn's tool call in lexical order. | macOS, Linux, Windows |
install_ffmpeg | Install the ffmpeg binary used by start_recording's video capture (Linux/Windows; macOS records natively and needs no ffmpeg). | macOS, Linux, Windows |
Configuration, permissions, health, updates and extensions. Reference.
| Tool | Description | Platforms |
|---|---|---|
get_config | Return the current cua-driver-rs configuration. | macOS, Linux, Windows |
set_config | Update cua-driver-rs configuration. | macOS, Linux, Windows |
check_permissions | Report TCC permission status for Accessibility and Screen Recording. | macOS, Linux, Windows |
health_report | Single-call end-to-end driver diagnostics. | macOS, Linux, Windows |
check_for_update | Check the saved stable/nightly Cua Driver channel for a release on GitHub. | macOS, Linux, Windows |
install_extension | Preview or install one Driver-managed optional extension. | macOS, Linux, Windows |