# 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 canvas-only or
custom-drawn UIs. It verifies each consequential action (reports a DEVIATION instead of a hollow
"success"), and routes every call through a single safety gate (allow / confirm /
block). 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).

## 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 only configures the
optional autonomous daemon.

## Use as an autonomous daemon (clawdcursor brings the model)

    clawdcursor doctor    # configure the built-in LLM (13 providers supported)
    clawdcursor agent     # HTTP + MCP daemon on 127.0.0.1:3847

`clawdcursor agent --no-llm` exposes the HTTP tool surface only (your agent supplies the brain).

## Tool surface (compact — recommended, ~1500 tokens of catalog)

- computer — mouse, keyboard, screenshot (raw I/O)
- accessibility — drive UI by element name; compile a fused el_NN UI map and act on {element_id, snapshot_id} (survives layout shifts)
- window — launch, focus, resize apps
- system — clipboard, OCR, shortcuts, webview detection, pause_for_user (hand the desktop to the user at a roadblock)
- browser — Chrome DevTools Protocol for Electron / WebView2 apps
- task — hand a whole task to the built-in autonomous loop
- batch — run a guarded, safety-gated sequence of the above in one call

98 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

Every tool call routes through one `safety.evaluate()` chokepoint regardless of
transport (stdio or HTTP). Sensitive actions auto-elevate to Confirm. HTTP requires
a bearer token. Local-only by default. An on-screen "desktop control in progress"
indicator shows whenever an agent is driving — double-click it to stop.
At a roadblock (sign-in, 2FA, CAPTCHA) the agent pauses instead of failing: the
glow turns blue, the prompt 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.

## 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
