Screen tools
The desktop, screen size, cursor position and zoomed crops.
The desktop, screen size, cursor position and zoomed crops.
| Tool | Description | Platforms |
|---|---|---|
get_desktop_state | Capture the full display in true screen pixels, full size unless max_image_dimension caps it. | 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 |
Served by cua-driver mcp; see MCP tools for every tool.
get_desktop_state#Effect: read-only. Platforms: macOS, Linux, Windows.
Capture the full display in true screen pixels, full size unless max_image_dimension caps it. Use its PNG as the coordinate source for actions whose target is {kind:"desktop",display_id:"primary"}. Returns the true screen size and backing scale factor. Vision-only: no AX tree walk.
Parameters on every platform
| Parameter | Type | Default | Description |
|---|---|---|---|
max_image_dimension | integer | Optional long-edge cap for the returned PNG, in pixels (aspect ratio preserved). Omitted or 0 returns the full-size capture. When the cap downsizes the image, the response reports screenshot_original_width/height, and x/y read off it for this session's later scope:"desktop" actions (or passed with its capture_id) are mapped back to the full-size frame automatically. Minimum: 0. | |
screenshot_out_file | string | Write PNG here instead of base64. | |
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. |
get_screen_size#Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
Return the logical size of the main display in points plus its backing scale factor. Agents click in points; Retina displays have scale_factor 2.0. Requires no TCC permissions.
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. |
get_cursor_position#Return the current mouse cursor position in screen points (origin top-left).
Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
| 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. |
zoom#Effect: read-only, idempotent. Platforms: macOS, Linux, Windows.
Capture a cropped JPEG of a window region (x1,y1)–(x2,y2) in screenshot pixel coordinates, with 20% padding added on each side. The output image is at most 500 px wide.
After a zoom, pass from_zoom=true to click/type_text to auto-translate coordinates back to full-window space. Coordinate actions return screenshot_context_missing when no current snapshot contains a screenshot owned by this session. from_zoom actions return zoom_context_missing when the zoom was never created or was replaced; call get_window_state, then zoom, again on the same connection.
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
pid | integer | Optional target pid. When omitted, the driver resolves the unique current snapshot for this session and window. | |
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. | |
window_id | integer | required | CGWindowID from list_windows. |
x1 | number | required | Left edge of region in screenshot pixels. |
x2 | number | required | Right edge of region in screenshot pixels. |
y1 | number | required | Top edge of region in screenshot pixels. |
y2 | number | required | Bottom edge of region in screenshot pixels. |
Example arguments
{"window_id":1,"x1":100,"y1":200,"x2":100,"y2":200}