# clawdcursor

> The local MCP server that gives any tool-calling agent safe control of the real
> desktop — clicks, types, reads the screen, opens apps, drives any GUI. Local-only
> (binds 127.0.0.1, bearer-token auth on HTTP, no telemetry by default), cross-OS
> (Windows / macOS / Linux), works with any model.

How it works: clawdcursor compiles the screen into one fused, confidence-scored UI
map (accessibility tree + OCR) with stable element ids, and acts on elements by
name/id in the cheap tiers — dropping to screenshot/vision (which DOES use live
pixel coords off the current frame) only as a last resort, for a target with no
name and no visible text. It verifies each consequential action (reports a DEVIATION instead of a hollow
"success"), and stops the moment the user says so. This is the fallback/last-mile layer: prefer a native API, a CLI, direct
file edits, or existing browser automation when those exist; reach for clawdcursor
when the only remaining surface is a GUI (a legacy app, a canvas, an app with no
public API).

## One ladder

SEE: `accessibility {"action":"read_tree"}` → `system {"action":"copy_all_text"}` → `system {"action":"ocr"}`.
ACT: `accessibility {"action":"invoke","name":"Send"}` or `set_value` → `accessibility {"action":"smart_click","target":"<label>"}` → `computer {"action":"screenshot"}`, then `computer {"action":"click","x":…,"y":…}`.
Take the next rung only when the one before found nothing. `smart_click` finds a visible label by OCR and clicks it, with no screenshot; a screenshot and a coordinate click are for a target with no name and no visible text.

## Install

- Recommended (any OS): `npm i -g clawdcursor`  (requires Node.js 20+)
- Windows one-liner: `powershell -c "irm https://clawdcursor.com/install.ps1 | iex"`
- macOS / Linux one-liner: `curl -fsSL https://clawdcursor.com/install.sh | bash`
- One-time, always required: `clawdcursor consent --accept`
- macOS only, after install: `clawdcursor grant`  (approve Accessibility + Screen Recording)

`consent` also registers clawdcursor as a Skill in every agent framework it detects
(Claude Code, OpenClaw, Codex, Cursor) — so you get this usage guide as a loadable
skill, not just raw tools. Re-run any time with `clawdcursor register-skill`.

## Use as an MCP server (your editor or agent brings the model)

Add to your editor's MCP config — if clawdcursor is installed globally:

    { "mcpServers": { "clawdcursor": { "command": "clawdcursor", "args": ["mcp", "--compact"] } } }

Or, with no global install (npx fetches it on demand, uses a global install if present):

    { "mcpServers": { "clawdcursor": { "command": "npx", "args": ["-y", "clawdcursor", "mcp", "--compact"] } } }

The `mcpServers` shape above works for Cursor, Windsurf, Claude Desktop, Cline and
Gemini CLI (`~/.gemini/settings.json`). These hosts use a DIFFERENT shape —
copying the one above into them will not work:

VS Code (Copilot) uses `servers`, not `mcpServers`, in `.vscode/mcp.json`:

    { "servers": { "clawdcursor": { "command": "clawdcursor", "args": ["mcp", "--compact"] } } }

Zed uses `context_servers` in `settings.json`:

    { "context_servers": { "clawdcursor": { "command": "clawdcursor", "args": ["mcp", "--compact"] } } }

OpenAI Codex uses TOML in `~/.codex/config.toml`. First launch can take a few
seconds, so raise the 10 s default startup timeout:

    [mcp_servers.clawdcursor]
    command = "clawdcursor"
    args = ["mcp", "--compact"]
    startup_timeout_sec = 30

opencode uses `mcp`, `type: "local"`, and an ARRAY `command`, in `opencode.json`:

    { "mcp": { "clawdcursor": { "type": "local", "command": ["clawdcursor", "mcp", "--compact"] } } }

Any other MCP host: register a stdio server, command `clawdcursor`, args `mcp --compact`.

WINDOWS: some hosts start the server without a shell and then cannot find
`clawdcursor` or `npx` (both are `.cmd` shims). If the server will not start, wrap
it in `cmd /c`:

    { "command": "cmd", "args": ["/c", "clawdcursor", "mcp", "--compact"] }

Claude Code: install the plugin instead of editing config — it registers the MCP
server (via npx) and bundles the usage skill in one step:

    claude plugin marketplace add AmrDab/clawdcursor
    claude plugin install clawdcursor@clawdcursor

Note: `clawdcursor doctor` is NOT needed for MCP use; it is a diagnostic.

## Use over HTTP

    clawdcursor agent     # HTTP MCP daemon on 127.0.0.1:3847; your agent drives the tools

clawdcursor never runs a model.
`clawdcursor agent --no-vision` (or `CLAWD_DISABLE_VISION=1`, also for stdio) sends no screenshot to any model: a call that would return one is refused with VISION_DISABLED; read the screen with accessibility or OCR.

## Tool surface (compact — recommended, ~7,000 tokens of catalog vs ~20,000 granular)

- accessibility — drive UI by element name; compile a fused el_NN UI map and act on {element_id, snapshot_id} (survives layout shifts)
- system — clipboard, OCR, shortcuts, webview detection, pause_for_user (hand the desktop to the user at a roadblock)
- window — launch, focus, resize apps
- browser — Chrome DevTools Protocol for Electron / WebView2 apps
- computer — raw keyboard and mouse (type, keys, scroll, drag); click x,y and screenshot are the last resort
- batch — run a guarded sequence of the above in one call

100+ granular tools (one schema per verb) are available by omitting `--compact`
(granular is the default surface) — enumerate them with `tools/list` on either
transport, if your runtime needs every primitive as a top-level tool.

## Safety

clawdcursor is a tool layer that runs with the user's own permissions. It does not
decide what you may do: there are no safety tiers and nothing is refused for being
"destructive". That decision is yours and your MCP host's permission prompts' (the
tools carry readOnlyHint / destructiveHint annotations for them). Before an irreversible
action the user didn't ask for (send, delete, pay, close unsaved work), ask with
`system pause_for_user`. Never type or ask for credentials. What clawdcursor always
enforces itself: the user's Stop, the pause, no stray input into an AI assistant's
window, and a hard key list — the combos that lock the machine or end the session are
never sent (Windows Win+L, Ctrl+Alt+Del; macOS Ctrl+Cmd+Q, Cmd+Shift+Q, Power; Linux
Super+L, Ctrl+Alt+Del, Ctrl+Alt+Backspace, Ctrl+Alt+F1-F12); every other
shortcut is allowed. HTTP requires a bearer token. Local-only by default. An on-screen pill shows whenever an agent is
driving and what it is doing ("Typing in Edge") — its Stop button (or a double-click) stops it. A stop holds
across restarts: every call returns "stopped by the user" until the user's Resume on a
`system pause_for_user` prompt gives control back. Never lift a stop any other way. Input is
refused ("foreground changed") when a window other than the one the agent was working
in is in front; `window focus` binds it to a window on purpose. Input is also refused when
the window in front is an AI assistant (Claude, ChatGPT, Codex, Cursor, VS Code, Windsurf, Zed)
that the agent did not focus or open on purpose, so text meant for an app never lands in a chat.
At a roadblock (sign-in, 2FA, CAPTCHA) the agent pauses instead of failing: the
prompt turns blue and says what to do, and the task continues when the
user clicks Resume. Outside agents use
`system pause_for_user` (ask for the one step only the user can do, and pass `done_when` so the pause ends as soon as they finish); `clawdcursor resume` answers from a terminal.
While you are driving the desktop, the user is watching the screen, not your chat: ask them on
the pause card (use `choices` when there are options), not in your own chat.
`pause_for_user` takes `choices` (2-6 short options, one button each) and/or `input`
(`{placeholder?, multiline?}`, a text box); the answer is `{status:"replied", choice:"<exact option text>"}`
or `{status:"replied", reply:"..."}`. It is the user's answer to your question: follow it. No tool call of yours can pick a
choice. Never ask for a password or secret on it.

## Links

- Site: https://clawdcursor.com
- Source: https://github.com/AmrDab/clawdcursor
- npm: https://www.npmjs.com/package/clawdcursor
- Changelog: https://github.com/AmrDab/clawdcursor/blob/main/CHANGELOG.md