Browser input tools
Exact browser input over CDP: clicks, typing, pointer, dialogs, files and downloads.
Exact browser input over CDP: clicks, typing, pointer, dialogs, files and downloads.
| 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_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 |
Served by cua-driver mcp; see MCP tools for every tool.
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 (Linux Chromium; for example a browser inside a sandbox). input_route="dom_event" (synthetic el.click(), 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.
| Parameter | Type | Default | Description |
|---|---|---|---|
delivery_mode | "background" | "foreground" | "background" | background (default) refuses trusted input where it would activate the browser window (Linux Chromium). foreground accepts that activation, for a browser whose window nobody else is using (for example inside a sandbox). |
input_route | "trusted" | "dom_event" | "trusted" (default): Input.dispatchMouseEvent. It refuses rather than foregrounding a standalone browser. "dom_event": synthetic full-background DOM click, only when explicitly requested. Dispatch does not prove the control activated; refresh page state and verify the expected postcondition. | |
ref | string | Page element ref in the p<snapshot>:<index> namespace from get_browser_state. Refs are invalidated by navigation and by newer snapshots of the same tab. | |
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. Browser targets, tabs, and refs belong to the resolved lifecycle session. | |
tab_id | string | required | Opaque tab id from get_browser_state (session-scoped). |
target_id | string | required | Opaque browser target id minted by get_browser_state (session-scoped; never a CDP id). |
x | number | Viewport x (CSS px): alternative to ref. | |
y | number | Viewport y (CSS px): alternative to ref. |
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.
| Parameter | Type | Default | Description |
|---|---|---|---|
mode | "insert_text" | "keystrokes" | insert_text (default): bulk Input.insertText. keystrokes: per-character Input.dispatchKeyEvent. | |
ref | string | required | Page element ref in the p<snapshot>:<index> namespace from get_browser_state. Refs are invalidated by navigation and by newer snapshots of the same tab. |
replace | boolean | false (default): insert at the caret, appending to whatever the field already holds. true: select the element's whole content first so the text replaces it; with an empty text this clears the field. Replacement goes through the selection, so beforeinput/input still fire and framework state stays consistent. | |
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. Browser targets, tabs, and refs belong to the resolved lifecycle session. | |
tab_id | string | required | Opaque tab id from get_browser_state (session-scoped). |
target_id | string | required | Opaque browser target id minted by get_browser_state (session-scoped; never a CDP id). |
text | string | required | Text to type. |
Example arguments
{"target_id":"<target_id>","tab_id":"<tab_id>","ref":"<ref>","text":"<text>"}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.
| Parameter | Type | Default | Description |
|---|---|---|---|
action | "hover" | "right_click" | "double_click" | "scroll" | "drag" | required | Pointer gesture. scroll needs delta_x or delta_y; drag needs destination_ref or to_x/to_y. |
delivery_mode | "background" | "foreground" | "background" | background (default) refuses trusted input where it would activate the browser window (Linux Chromium). foreground accepts that activation, for a browser whose window nobody else is using (for example inside a sandbox). |
delta_x | number | Horizontal scroll delta in CSS pixels. | |
delta_y | number | Vertical scroll delta in CSS pixels. | |
destination_ref | string | Drag destination page ref in the exact same frame. | |
input_route | "trusted" | "dom_event" | "trusted" | trusted sends CDP Input events; dom_event synthesizes DOM events in the page and requires ref. |
ref | string | Origin page ref. Alternative to x/y. | |
session | string | required | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. This tool requires the label that owns its browser target, tab, and refs. |
tab_id | string | required | Opaque tab id minted by get_browser_state. |
target_id | string | required | Opaque target id minted by get_browser_state. |
to_x | number | Drag destination viewport x in CSS pixels. | |
to_y | number | Drag destination viewport y in CSS pixels. | |
x | number | Origin viewport x in CSS pixels. | |
y | number | Origin viewport y in CSS pixels. |
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.
| Parameter | Type | Default | Description |
|---|---|---|---|
action | "inspect" | "accept" | "dismiss" | required | inspect returns the current dialog and its dialog_id; accept or dismiss resolves that exact dialog. |
delivery_mode | "background" | "foreground" | "background" | Requested foreground posture for accept/dismiss. Linux Chromium requires foreground; inspect is read-only. |
dialog_id | string | Opaque current dialog generation returned by action=inspect. | |
prompt_text | string | Sensitive response text, valid only when accepting a prompt dialog. | |
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. Browser targets, tabs, and refs belong to the resolved lifecycle session. | |
tab_id | string | required | Opaque tab id from get_browser_state (session-scoped). |
target_id | string | required | Opaque browser target id minted by get_browser_state (session-scoped; never a CDP id). |
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.
| Parameter | Type | Default | Description |
|---|---|---|---|
files | string[] | required | Absolute paths of 1 to 32 local regular files to assign to the input. Items: 1 to 32. |
ref | string | required | Page element ref in the p<snapshot>:<index> namespace from get_browser_state. Refs are invalidated by navigation and by newer snapshots of the same tab. |
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. Browser targets, tabs, and refs belong to the resolved lifecycle session. | |
tab_id | string | required | Opaque tab id from get_browser_state (session-scoped). |
target_id | string | required | Opaque browser target id minted by get_browser_state (session-scoped; never a CDP id). |
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.
| Parameter | Type | Default | Description |
|---|---|---|---|
destination_root | string | required | Absolute, existing, canonical directory approved to receive the download. |
ref | string | required | Live page ref whose activation initiates the download. |
session | string | required | For multi-call work, prefer a short public session label and repeat it on every call that accepts it. This tool requires the label that owns its browser target, tab, and refs. |
tab_id | string | required | Opaque exact tab id from get_browser_state. |
target_id | string | required | Opaque exact browser target id from get_browser_state. |
Example arguments
{"session":"<session>","target_id":"<target_id>","tab_id":"<tab_id>","ref":"<ref>","destination_root":"<destination_root>"}