Typing tools
Type text into a field or window.
Type text into a field or window.
Served by cua-driver mcp; see MCP tools for every tool.
type_text#Effect: destructive. Platforms: macOS, Linux, Windows.
Insert text into the target pid via AXSetAttribute(kAXSelectedText). Works for standard Cocoa text fields and text views. No keystrokes are synthesized: special keys (Return / Escape / arrows) go through press_key / hotkey. For Chromium / Electron inputs that don't implement kAXSelectedText, the tool falls back to CGEvent character synthesis automatically when the estimated route stays within the daemon transport budget. Longer synthesized routes are refused before character events and return a safe chunk size; one-call AX insertion remains uncapped.
Optional element_token (from the last get_window_state snapshot) directs the write to a specific field. Without element_token, the write goes to the pid's currently focused element.
WEB CONTENT (Chromium/WebKit/Electron: browser tabs, Slack, VS Code, X's compose box): AXValue is not independent proof that the renderer/DOM observed an AX write or synthesized keystrokes. The driver detects this at the element level (an AXWebArea ancestor) and refuses to trust AXValue-only read-back there. Electron AX targets that are web content or cannot be proven native refuse background delivery before mutation because the AX route cannot establish exact renderer focus; use the px form or explicit foreground delivery. Other web-content paths return effect:"unverifiable" + escalation, never a false "confirmed" (a browser's own native address bar/toolbar stays trusted). For a browser TAB the reliable path is the page tool (drives the DOM via CDP); for an embedded web view use this tool's px form: pass x,y (no element_token) to pixel-click the field then type, in one call. NOTE: a px focus-click won't reliably open+focus a CLOSED control; AX-press to open/activate it first (works in the background), then px-type. Always confirm via the screenshot; if px-background still drops, escalate to delivery_mode:"foreground".
macOS parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
delay_ms | integer | Milliseconds between characters in the CGEvent fallback path. Default 30. Ignored when the AX path succeeds. Range: 0 to 200. | |
delivery_mode | "background" | "foreground" | Best-effort-background ladder rung (default "background"). "background": AX insert, then CGEvent keystrokes if needed; no focus steal; native controls can be confirmed via AXValue read-back, while web-content writes remain effect:"unverifiable". "foreground": briefly front the window, type, restore the prior frontmost; the explicit last resort for focus-sensitive surfaces (e.g. WhatsApp/Catalyst) where background keystrokes don't land. Re-call with "foreground" when a background attempt remains unverifiable and a fresh snapshot shows the text did not appear. | |
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. | |
pid | integer | Target process ID. | |
scope | "window" | "desktop" | "window" | Use desktop with no pid/window_id to type into the frontmost application. |
text | string | required | Text to insert at the target's cursor. |
window_id | integer | CGWindowID. Omit when element_token is supplied (the token carries it). | |
x | number | Screenshot-pixel X of the field to type into: the element px action form. Pass x,y (no element_token) and the tool pixel-clicks there to establish real renderer focus, then types. Use for Chromium/Electron inputs the AX path can't reach. Read straight off the get_window_state PNG, same convention as click. | |
y | number | Screenshot-pixel Y of the field (see x). |
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 | Preferred per-call target: an exact window (kind="window", pid, window_id) or the primary desktop (kind="desktop", display_id="primary"). |
Example arguments
{"text":"<text>"}