Pointer, cursor and browser

Drag, scroll and move the pointer; the agent cursor; web pages and browser input.

Served by cua-driver mcp; see MCP tools for every tool.

Pointer tools#

Drag, scroll, move the pointer, and press or release buttons.

drag#

Effect: destructive. Platforms: macOS, Linux, Windows.

Parameters on every platform

Example arguments

{"from_x":100,"from_y":200,"to_x":100,"to_y":200}

scroll#

Effect: mutating. Platforms: macOS, Linux, Windows.

Parameters on every platform

Example arguments

{"direction":"up"}

move_cursor#

Effect: mutating, idempotent. Platforms: macOS, Linux, Windows.

Parameters on every platform

Example arguments

{"x":100,"y":200}

mouse_button_down#

Press and hold a mouse button at (x,y) via background X11 delivery. Does not release the button; pair with mouse_drag / mouse_button_up. Returns the current held-button state.

Effect: destructive. Platforms: Linux.

Example arguments

{"pid":1,"window_id":1,"x":100,"y":200}

mouse_button_up#

Release a previously-held mouse button via background X11 delivery. If x/y are omitted, releases at the last held position. Returns the current held-button state.

Effect: destructive. Platforms: Linux.

mouse_drag#

Move a previously-held mouse button to a new point via background X11 delivery. Requires an active mouse_button_down state; does not release the button. Returns the updated held-button state.

Effect: destructive. Platforms: Linux.

Example arguments

{"x":100,"y":200}

parallel_mouse_drag#

Run multiple mouse drag gestures concurrently via Linux MPX/XI2 virtual master pointers. Each drag item runs on its own session-scoped master pointer (true same-window concurrent draws on X11). Each item presses once, glides continuously through its whole path, and releases once: one smooth held drag, not a chain of clicks. A path is given either as a straight segment (from_x/from_y → to_x/to_y) or as a function fn = y(x) sampled over [x_from, x_to] in window-local pixels (e.g. fn:"x" is a diagonal, fn:"300+120*sin(x/40)" a sine wave). Functions support + - * / ^, sin/cos/tan, sqrt, abs, exp, ln, pi, e.

Effect: destructive. Platforms: Linux.

Example arguments

{"drags":[{"session":"<session>","window_id":1},{"session":"<session>","window_id":1}]}

Agent cursor tools#

Show, animate and style the agent cursor.

set_agent_cursor_enabled#

Show or hide the agent cursor owned by a session.

Effect: mutating, idempotent. Platforms: macOS, Linux, Windows.

Example arguments

{"session":"<session>","enabled":false}

set_agent_cursor_motion#

Configure the movement style, timing, effects and visibility timing for a session cursor.

Effect: mutating, idempotent. Platforms: macOS, Linux, Windows.

Example arguments

{"session":"<session>"}

set_agent_cursor_theme#

Select an already-installed cursor theme for a session.

Effect: mutating, idempotent. Platforms: macOS, Linux, Windows.

Example arguments

{"session":"<session>","theme_id":"<theme_id>"}

get_agent_cursor_state#

Return the session cursor's theme, semantic playback, position, visibility, and motion.

Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.

Example arguments

{"session":"<session>"}

Page tools#

Read and act on web pages, and prepare and navigate browsers.

page#

Legacy browser compatibility tool. Prefer get_browser_state and the typed browser_* tools for exact targeting, endpoint ownership, and consent. Read-only get_text and query_dom remain available by default. Mutating actions require the daemon operator to set CUA_DRIVER_ENABLE_LEGACY_PAGE_MUTATIONS=1 before daemon startup (restart the daemon after changing it); this escape hatch does not provide the typed browser surface's exact binding or existing-profile grant guarantees. Supports Chrome, Brave, Edge, Safari (via AppleScript on macOS), Electron apps (via CDP), Chromium/Firefox on Windows (via UIA for read; CDP for execute_javascript when --remote-debugging-port is set), and WKWebView/Tauri/AT-SPI fallbacks.

Actions:

• execute_javascript: Run JS and return the result.
• get_text: Extract visible text from the page.
• query_dom: Find elements matching a CSS selector.
• click_element: Click a CSS-selected element AND animate the agent cursor to its on-screen center first (so the user sees what the agent is doing). Prefer over execute_javascript('el.click()') whenever you want visible cursor feedback.
• insert_text: Insert text at whatever currently holds DOM focus in one native operation (CDP Input.insertText); no synthesized key events, but more durable than a one-shot execute_javascript write since rich-text editors already have to treat it like an IME commit. Try this before type_keystrokes on a contenteditable that discarded an execute_javascript write. Click/focus the target field first.
• type_keystrokes: Type text via real per-character keystroke events into whatever currently holds DOM focus. Slower than insert_text but the most durable rung: use it when insert_text also gets discarded, or the editor's own keydown/keyup handlers need to see real keys. Click/focus the target field first.
• enable_javascript_apple_events: macOS-only; patch the browser's Preferences to allow JS from Apple Events (Chrome/Brave/Edge, requires user confirmation and a browser restart).

Effect: mutating. Platforms: macOS, Linux, Windows.

Example arguments

{"action":"execute_javascript"}

get_browser_state#

Read-only browser inspection. Mode 1 (bind): pass pid + window_id of a native browser window to classify it, correlate it to a CDP target (exact-or-refuse), and mint a session-scoped target id plus tab ids. Mode 2 (snapshot): pass target_id + tab_id. The dom_refs_v1 compatibility format returns composed DOM refs. semantic_v2 joins accessibility, DOM, layout, and viewport state; ranks visible content before retained/offscreen state; and returns a semantic outline, typed action refs, content refs, scoped reads, and opaque continuation. Never performs setup: a browser that is not attached yet refuses with browser_consent_required or browser_requires_setup, and detail.next_call names the browser_prepare call that attaches it. Use this route for any web page in Chrome, Edge or Brave; desktop pointer tools move the user's pointer. Setup and recovery: get_guide({topic:"browser"}).

Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.

browser_prepare#

Attach the browser tools to a browser. For a page in the user's running Chrome, Edge or Brave, call it once with pid, window_id, session and strategy {"kind":"existing_profile"} when get_browser_state refuses with browser_consent_required or browser_requires_setup; then call get_browser_state again and act with browser_click, browser_type or browser_pointer. It attaches, or refuses with nothing changed and says why. Explicitly prepare an owned DevTools endpoint for a browser. pid is required for an existing process or existing-profile attachment, and optional only for allow_launch=true with an isolated profile. Existing endpoints are detected without side effects. Acting setup for an isolated profile follows the runtime permission mode and optional capability manifest. It requires allow_launch=true, launches a separate browser, and never copies, modifies, or terminates the requested user profile. Without pid, only a platform-attested system Chrome/Edge installation (or a root-owned package payload on Linux) is eligible; redirects and user-controlled locations fail closed. Existing-profile attachment is explicit and follows the runtime's immutable permission mode: standard requires an explicit --grant existing-profile launch grant or an embedding authorization host, bounded requires a launch-approved exact resource manifest, and unrestricted requires explicit trusted startup risk acceptance. Ordinary MCP transport approval never proves profile authorization. On proven platforms, an authorized request also permits one bounded exact-window setup: open the recognized browser product's fixed remote-debugging page, toggle its uniquely matched per-instance checkbox, prove the PID-owned loopback endpoint, and close the temporary tab. Every visible effect is reported; ambiguity is refused. Where attaching would bring the browser in front of the user's app (macOS Chrome shows its own remote-debugging prompt in front whenever the driver opens a new browser connection; sessions for the same browser share one approved connection, kept for up to 30 minutes idle and 8 hours in total, so later sessions do not prompt again), existing-profile attachment refuses with background_unavailable unless delivery_mode is "foreground" (the app that was in front is brought back afterwards) or the browser window is on another Space than the user's, where it attaches in the background while the driver reverts the browser's own brief activations. A driver-owned isolated launch result carries an advisory lifecycle object: the browser process ends with the calling session after idle_expires_in_seconds without session activity, an isolated_named profile persists after the session and an isolated_new profile does not, and explicit end, disconnect, revocation or shutdown end it earlier. Setup and recovery: get_guide({topic:"browser"}).

Effect: destructive. Platforms: macOS, Linux, Windows.

browser_navigate#

Navigate one tab of an exactly-bound browser target to a new URL (http/https/about only). Refused for heuristic bindings. Navigation invalidates all p<snapshot>:<index> refs for the tab.

Effect: mutating. Platforms: macOS, Linux, Windows.

Example arguments

{"target_id":"<target_id>","tab_id":"<tab_id>","url":"<url>"}

Browser input tools#

Exact browser input over CDP: clicks, typing, pointer, dialogs, files and downloads.

browser_click#

Click a page element (by ref) or viewport coordinates in an exactly-bound tab. Default route is trusted hardware-like input (Input.dispatchMouseEvent), and refuses where that route cannot preserve standalone-browser background posture unless delivery_mode="foreground" accepts that the browser window may activate (including Linux Chromium configurations whose trusted route cannot stay in the background; for example a browser inside a sandbox). input_route="dom_event" (synthetic pointer and mouse down/up/click sequence at the element's center, ref required) is used only when explicitly requested; it proves dispatch, not control activation, because trust-gated controls may ignore synthetic events. Refused for heuristic bindings.

Effect: mutating. Platforms: macOS, Linux, Windows.

Example arguments

{"target_id":"<target_id>","tab_id":"<tab_id>"}

browser_type#

Type text into an exactly-bound tab via the Input domain. mode="insert_text" (default) uses Input.insertText; mode="keystrokes" dispatches per-character key events. Both insert at the caret, so typing into a field that already holds text appends to it; pass replace=true to set the field instead, or to clear it by typing an empty string. Pass a ref to an editable element from the latest snapshot. A ref is required; heuristic bindings are refused.

Effect: mutating. Platforms: macOS, Linux, Windows.

Example arguments

{"target_id":"<target_id>","tab_id":"<tab_id>","ref":"<ref>","text":"<text>"}

browser_select#

Select one option of a native HTML <select> ref on an exactly-bound tab without opening its popup. Pass exactly one of label or value; exactly one option must equal it. Refuses non-native, multiple-selection, and disabled selects, disabled options, and zero or ambiguous matches before changing anything. A change dispatches bubbling input and change events; they are synthetic, so verify the page accepted the selection. Selecting the option that is already selected dispatches no events.

Effect: mutating. Platforms: macOS, Linux, Windows.

Example arguments

{"target_id":"<target_id>","tab_id":"<tab_id>","ref":"<ref>"}

browser_pointer#

Perform hover, right-click, double-click, scroll, or drag in an exactly-bound browser tab. Semantic refs must declare pointer for hover, right-click, double-click, and drag; scroll accepts a scroll or pointer capability. The trusted route uses CDP Input events and refuses if standalone background posture cannot be preserved. The explicit dom_event route requires a page ref and synthesizes full-background DOM events. Never activates or brings a tab to the foreground.

Effect: mutating. Platforms: macOS, Linux, Windows.

Example arguments

{"target_id":"<target_id>","tab_id":"<tab_id>","session":"<session>","action":"hover"}

browser_dialog#

Inspect or resolve a page-owned JavaScript alert, confirm, prompt, or beforeunload dialog on one exactly-bound tab. This never handles browser permission UI, extension UI, native dialogs, or file pickers. Inspect returns an opaque dialog_id; accept/dismiss require that exact current id. Resolution defaults to background delivery; Linux callers must explicitly request foreground delivery because Chromium's native modal cannot be resolved there without changing foreground posture.

Effect: mutating. Platforms: macOS, Linux, Windows.

Example arguments

{"target_id":"<target_id>","tab_id":"<tab_id>","action":"inspect"}

browser_set_input_files#

Assign one or more explicit absolute local files to an exact live <input type=file> ref through CDP. This bypasses native file pickers, rejects symlinks and non-regular files, and never returns local paths.

Effect: mutating. Platforms: macOS, Linux, Windows.

Example arguments

{"target_id":"<target_id>","tab_id":"<tab_id>","ref":"<ref>","files":["<file>"]}

browser_download#

Trigger one download through an exact live browser ref and save it inside an explicitly approved directory. Requires MCP-host destructive-tool approval, refuses ambiguous or stale capabilities, and never returns the source URL, filename, or destination path.

Effect: destructive. Platforms: macOS, Linux, Windows.

Example arguments

{"session":"<session>","target_id":"<target_id>","tab_id":"<tab_id>","ref":"<ref>","destination_root":"<destination_root>"}