desktop-mcp

Windows desktop-control MCP server: screenshot, window management, mouse/keyboard input, and ffmpeg screen-recording, config-gated by tool group (input off by default) -- built to the same standard as mcp-factory and rag-mcp: own pyproject, fastmcp server, honest README, real test suite.

Quickstart

pip install desktop-mcp

// ~/.claude.json (or any MCP-host stdio client config)
{
  "mcpServers": {
    "desktop-mcp": {
      "command": "desktop-mcp"
      // or: "command": "python", "args": ["-m", "desktop_mcp"]
    }
  }
}

window/input/record tool groups are env-gated -- input stays off unless you explicitly opt in. See Env vars below for the full table.

Tool groups

A disabled group returns a structured policy_refusal error (never a silent no-op, never a crash). Input actions are additionally rate-capped (default 60 actions/min, tunable via DESKTOP_MCP_RATE_LIMIT_PER_MIN) -- exceeding the cap returns a structured rate_limited error.

This is defense-in-depth: harness-level permission prompts are the first gate, but the server itself refuses input/window/record actions unless its own env explicitly enables them, so a misconfigured or overly-permissive harness can't turn on capabilities the operator didn't opt into for this process.

Honest-capabilities table

Every claim below maps to the file that implements it and the test(s) that verify it -- no capability is asserted without a corresponding implementation + test.

Limitations (read before relying on this)

• UIPI (User Interface Privilege Isolation). A medium-integrity process (this server, unless you elevate it) cannot send input to or manipulate windows owned by a higher-integrity (elevated/admin) process. Window and input tools surface this as a structured window_action_failed / input_failed error naming UIPI, never a silent no-op -- but there is no workaround short of running the server elevated, which this project does not do or recommend.
• DPI scaling. The server sets per-monitor-v2 DPI awareness at startup so mss pixel coordinates and pyautogui point coordinates should agree on scaled displays. This bootstrap is unit-tested for idempotency/no-crash only -- actual coordinate agreement on a live multi-DPI multi-monitor setup has not been automated-tested and should be spot-checked if you're targeting a non-100%-scaled monitor.
• UAC secure desktop. When Windows switches to the secure desktop (UAC elevation prompts, Ctrl+Alt+Del, lock screen), no process running on the regular desktop -- including this server -- can see or interact with it. Screenshots will show whatever was on the regular desktop before the switch; input calls will not reach the secure desktop at all.
• Single machine, local only. No network transport, no remote control. stdio only, spawned by the MCP host on the same machine.
• Input group is off by default in this repo's own registration. See ~/.claude.json's desktop-mcp entry -- DESKTOP_MCP_ENABLE_INPUT is not set there. Enabling it is a deliberate per-registration operator choice, not a code change.
• pyautogui failsafe. FAILSAFE=True is intentional: slamming the cursor into a screen corner mid-action raises inside pyautogui and aborts the call. This can interrupt an in-flight mouse_drag. Treated as acceptable v1 behavior (see plan's Open questions) -- it's a deliberate human kill-switch, not a bug.
• No OCR / vision analysis. Screenshots are raw PNGs; interpreting their content is the consumer's job, not this server's.
• No clipboard tools. Credential-adjacent surface, deferred to a v2 with its own safety design.
• Not registered with the mcp-factory hub. This ships as a standalone repo (own pyproject, own venv-free system-Python312 install), matching the rag-mcp model. Hub/registry integration is a v2 candidate.

Env vars

Usage examples

// A tool call from the MCP host, illustrative -- not a shell command.
{"tool": "screenshot", "arguments": {"monitor": 0}}
// -> {"ok": true, "path": "C:\\Users\\...\\Temp\\desktop-mcp-scratch\\screenshot-....png", "w": 3840, "h": 1080, "monitor": 0}

{"tool": "record_start", "arguments": {"fps": 30, "max_duration_s": 30}}
// -> {"ok": true, "path": "...\\recording-....mp4", "pid": 12345, "fps": 30, "max_duration_s": 30}
{"tool": "record_stop", "arguments": {}}
// -> {"ok": true, "path": "...\\recording-....mp4", "bytes": 800560, "duration_s": 3.13}

// input group disabled (default):
{"tool": "mouse_click", "arguments": {"x": 500, "y": 500}}
// -> {"ok": false, "error": {"type": "policy_refusal", "group": "input", "required_env": "DESKTOP_MCP_ENABLE_INPUT", ...}}

Testing

# unit suite (mocked backends, no real screen/input/recording touched)
python -m pytest -q

# handshake check -- prints every registered tool name
python scripts/list_tools.py

# real-hardware smokes (real screenshot PNG, real ~3s screen recording;
# never input-injection -- see safety rails above)
DESKTOP_MCP_LIVE=1 python -m pytest -q -k live_screenshot
DESKTOP_MCP_LIVE=1 python -m pytest -q -k live_record

Install

pip install -r requirements.txt   # or: pip install .
# deps: fastmcp==3.4.2, mss==10.2.0, pyautogui==0.9.54, PyGetWindow==0.0.9, pywin32==312
# also requires ffmpeg + ffprobe on PATH for the record group

Registered in ~/.claude.json as desktop-mcp (stdio, system Python312, observe+window+record groups enabled, input group absent from env).

Commercial support

Maintained by Jaimen Bell. For production MCP integrations, custom servers, or agent-reliability work, see jaimenbell.dev or sponsor ongoing maintenance via GitHub Sponsors.

mcp-name: io.github.jaimenbell/desktop-mcp