All tools
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.
Common parameters#
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.
Action results#
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.
App and window tools#
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 top-level windows known to WindowServer, including off-screen ones (minimized, other Space, hidden): layer-0 only without pid, every layer with pid. | 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 |
Window state tools#
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 |
Screen tools#
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 tool#
Click by element or pixel. Reference.
| Tool | Description | Platforms |
|---|---|---|
click | Click a target pid. | macOS, Linux, Windows |
Double-click and right-click tools#
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 |
Pointer tools#
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 |
Typing tools#
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 |
Key and shortcut tools#
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 |
Value and clipboard tools#
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 |
Batch and script tools#
Run several action tools, or a script that drives them, in one call. Reference.
| Tool | Description | Platforms |
|---|---|---|
run_steps | 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 |
run_script | Run a JavaScript program that drives apps through Cua Driver, in ONE call: loops, conditions, reads and checks between actions, and only the result comes back. | macOS, Linux, Windows |
Page tools#
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 | Attach the browser tools to 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 |
Browser input tools#
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_select | Select one option of a native HTML <select> ref on an exactly-bound tab without opening its popup. | 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 |
Session tools#
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 |
Agent cursor tools#
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 |
Recording tools#
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 and maintenance tools#
Configuration, permissions, health, updates, extensions and on-demand guides. 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 |
get_guide | Read Cua Driver guidance on demand, taken from the guide bundled with this driver (no skill install needed). | macOS, Linux, Windows |