Click tool
Click by element or pixel.
Click by element or pixel.
Served by cua-driver mcp; see MCP tools for every tool.
click#Effect: destructive. Platforms: macOS, Linux, Windows.
Click against a target pid. Prefer element_token over pixel coordinates: the token works on backgrounded / minimized / hidden / off-Space windows, identifies one exact snapshot element, and tells you what you're clicking via the cached element's role + label. Reach for x, y only when the target is a canvas / video / WebGL / custom-drawn surface that doesn't appear in the AX tree.
Two addressing modes:
element_token (from get_window_state): AX action path. Works on backgrounded/hidden windows. No cursor move, no focus steal. The snapshot cache is scoped per (pid, window_id) and is replaced by the next snapshot of the same window: re-snapshot every turn before clicking.
x, y (window-local screenshot pixels, top-left origin of the PNG returned by get_window_state): CGEvent path. Synthesizes mouse events and posts to pid. Use modifier for cmd/shift/option/ctrl. Needs a visible on-screen window to anchor the conversion.
button: "left" (default), "right", or "middle". Defaults to left so the field is fully back-compat: omit it and you get the legacy left-click behaviour. Pixel path: routes through the CGEvent left/right/middle mouse-button primitives. AX path: "right" maps to AXShowMenu (same surface as the dedicated right_click tool); "middle" has no AX equivalent and falls back to a pixel middle-click at the element's center.
action: press (default), show_menu, pick, confirm, cancel, open.
from_zoom: set true after a zoom call to auto-translate zoom-image pixel coordinates to full-window space.
macOS parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
action | string | AX action: press, show_menu, pick, confirm, cancel, open. | |
button | "left" | "right" | "middle" | Mouse button. Default: "left"; omit for legacy left-click behaviour. Pixel path uses the matching CGEvent primitive; AX path maps "right" to AXShowMenu and falls back to a pixel middle-click at the element's center for "middle". | |
capture_id | string | Optional immutable source capture ID returned by get_window_state or get_desktop_state. With x,y, Driver atomically admits and consumes that exact capture before dispatch; stale, mismatched, or out-of-bounds captures are refused without fallback. | |
count | integer | Click count (pixel path only). Default 1. | |
debug_image_out | string | Optional file path. When set on a pixel-addressed click, captures a fresh screenshot, draws a red crosshair at (x, y), and writes the PNG. Use to verify coordinate spaces. Requires window_id; incompatible with from_zoom. | |
delivery_mode | "background" | "foreground" | Best-effort-background ladder rung (default "background"). "background": perform the AX action or post the CGEvent without fronting. "foreground": briefly front the window, act, let transient UI settle, then restore the prior frontmost app. Requires window_id. Modified clicks require "foreground" so macOS observes physical modifier-key state. A generic click has no independent postcondition read-back, except selection of list-like AX rows whose AXSelected state can be confirmed; otherwise confirm the effect from a fresh state snapshot. Use the agent loop: background AX (element_token) → snapshot → background pixel (x/y) → snapshot → delivery_mode:"foreground". | |
element_token | string | Opaque per-snapshot element handle from structuredContent.elements[].element_token. Returns an explicit stale error naming the current snapshots once a newer read supersedes it. | |
from_zoom | boolean | When true, x and y are in the last zoom image for this pid; driver translates back to full-window coordinates. | |
modifier | string[] | Modifier keys: cmd, shift, option/alt, ctrl. | |
pid | integer | Target process ID. | |
scope | "window" | "desktop" | Coordinate frame for a windowless screen-absolute click (default "window"). Pass "desktop" when sending x,y with NO pid/window_id: the coordinates are then true screen pixels (read from get_desktop_state with scope="desktop"). Per-call; not a setting. | |
window_id | integer | Target window ID. Omit when element_token is supplied (the token carries it). | |
x | number | X in screenshot pixels. A window target uses the get_window_state PNG; a desktop target uses the native get_desktop_state PNG. The driver reverses Retina backing scale and any window-image downscale. | |
y | number | Y in screenshot pixels from the image selected by target. |
Parameters on every platform
| Parameter | Type | Default | Description |
|---|---|---|---|
session | string | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. Omit it to use the authenticated transport's implicit lifecycle session. | |
target | window target | desktop target | Exact capture/input target selected independently for each action. display_id="primary" is the portable desktop target in this release. Platforms that cannot address another display reject it explicitly rather than silently changing coordinate spaces. |