A visible, human-like cursor for AI agents: drive any Mac app or browser tab over MCP, with text-first reads that save tokens. One setup command connects Claude Code, Cursor, Codex, VS Code, Windsurf, Claude Desktop and Gemini CLI.
AgentCursor defines 24 tools with explicit schemas and descriptions. Most tools have clear action verbs (desktop_click, read_page, click_text) and detailed parameter descriptions. However, several tools lack output schema documentation, and some descriptions could be more concise. Parameter schemas are well-typed with Zod validation visible in source. Error handling guidance is minimal, most tools return simple text confirmations without recovery hints. The desktop_* tools are well-designed for composition (e.g., desktop_read returns refs that desktop_click consumes), following the tool-chain pattern. Browser tools (read_page, click, type) similarly chain well. Overall solid definitions with room for output schema clarity and error guidance.
Human-like move + click on an element ([ref]) or x/y. Supports button, double-click, and stealth (trusted-event) mode.
Identification + interaction in one step: find the element that best matches the given text/label, then human-move the cursor to it and click. Re-reads the page if the element isn't there yet. `nth` picks a later match, `stealth:true` delivers trusted events, `double` double-clicks.
List running Mac apps; * marks the frontmost one.
Move the real cursor along a human path and click: a [dN] ref, visible text/label, or screen x/y. Brings the app to the front first.
Press a key or shortcut in the current app: enter, esc, tab, up, cmd+s, cmd+shift+t, ctrl+c.
Move the real cursor to a ref, label, or x/y without clicking (menus, tooltips, hover states).
Output schemas not documented. Tools return text or image content but LLMs cannot see structured field definitions for downstream chaining. E.g., desktop_read returns formatted text with [dN] refs, but the response structure is not formally declared.
Error handling lacks recovery guidance. Tools return simple confirmations ('clicked X', 'typed Y chars') but do not guide LLMs on failure modes. E.g., desktop_click could fail if ref is stale or element is off-screen, but no error classification or retry hint is provided.
Some parameter descriptions are generic or incomplete. E.g., desktop_key 'keys' param says 'Key or key combination to press' but does not enumerate valid formats (enter, esc, cmd+s, etc.). LLMs may hallucinate invalid key names.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 64 | 2026-07-28+ | v2 |
Open or switch to a Mac app by name (Notes, Slack, Finder, Safari...) and bring it to the front.
Read an app window as compact text: buttons, fields, links, menus and visible text, each with a [dN] ref and center point. Costs far fewer tokens than a screenshot, so call it before clicking. `find` returns only the best matches for a label. Defaults to the app you last opened or read.
Screenshot one app window (or the area around a ref), downscaled. Use only when desktop_read text is not enough: canvases, images, custom-drawn UI. The reply explains how to turn image pixels into screen x/y for desktop_click.
Scroll by dy (positive = down) and optional dx, over a ref, label or x/y (else where the cursor is). Refs expire after scrolling; desktop_read again.
Type with human timing. Clicks a field first when given ref, into (label) or x/y; otherwise types into the focused field. clear replaces the current text, submit presses Enter.
Run a JavaScript function in the active page and return its JSON result. Pass a function source string, e.g. `() => document.title` or `async () => (await fetch('/api/x', { method: 'POST', credentials: 'include' })).status`. Runs in the page realm via CDP, so it uses the page's own cookies/session, awaits promises, and is not blocked by the page CSP. Return value must be JSON-serializable. Use for reads and requests the UI has no button for; the debugger banner shows while it runs.
Identification: locate on-screen elements by their visible text or accessible name (shadow-DOM aware), the way a human scans a page. Returns ranked matches with [ref], role, and on-screen rect. Use when you don't already have a ref, then click/move_to/hover by [ref] — or use click_text to do it in one step.
Return the active tab's current URL.
Human-like move the cursor to an element or coordinates and fire hover events (mouseover, mouseenter). Essential for dropdowns, tooltips, navigation menus, and realistic workflow/testing automation.
Move the cursor to an element ([ref] from read_page) or to absolute viewport x/y along a human-like path. Does not click. stealth:true delivers trusted events via the debugger driver.
Navigate the active tab to a URL.
Press a single key on the focused element: Enter, Escape, Tab, Backspace, Delete, ArrowUp/Down/Left/Right, Home, End, PageUp, PageDown, Space, or a single character. Use to submit (Enter), dismiss dialogs (Escape), or tab between fields. stealth:true delivers a trusted key event via the debugger driver.
Read the current page: interactive elements with stable [ref] handles, their roles/names and on-screen rectangles, plus visible text. Call before clicking or typing by ref.
Capture the visible tab as an image, scaled so 1 image pixel = 1 click coordinate. SEE the page, then click(x,y)/move_to(x,y) at coordinates read off the image. This is the vision loop (screenshot -> decide coords -> click -> screenshot) and needs no DOM refs.
Scroll the page by dy (and optional dx) pixels in eased human steps.
Return current MCP server status, driver in use (extension or os), whether the browser bridge is connected, and the active tab URL if available. Use for health checks in long-running tests, CI workflows, and agent monitoring.
Type text with human key timing. If a ref is given, the input is human-clicked to focus first. stealth:true uses the debugger driver.
Wait until an element [ref] appears or some visible text is present (or specific condition), up to timeoutMs (default 10000). Supports condition: 'exists' | 'visible' | 'text'. Use in testing and automation flows for resilience on dynamic sites.
Tool descriptions could be more concise. Several exceed 200 chars (e.g., desktop_read at ~280 chars, desktop_click at ~180 chars). Baseline for A+ tools is 50-200 chars. Verbose descriptions waste tokens and bury key intent.
No tool annotations (readOnlyHint, destructiveHint, idempotentHint) visible in source. These help LLMs reason about side effects and retry safety. E.g., desktop_click is destructive but not marked; desktop_read is read-only but not marked.