desktop-mcp

# desktop-mcp

[![PyPI](https://img.shields.io/pypi/v/desktop-mcp)](https://pypi.org/project/desktop-mcp/)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.jaimenbell%2Fdesktop--mcp-blue)](https://registry.modelcontextprotocol.io)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![tests](https://img.shields.io/badge/tests-130%20%28128%20passing%2C%202%20skipped%29-brightgreen)](tests)

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](https://github.com/jaimenbell/mcp-factory) and rag-mcp: own
pyproject, fastmcp server, honest README, real test suite.

## Quickstart

```bash
pip install desktop-mcp
```

```jsonc
// ~/.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

| Group | Tools | Default state |
|---|---|---|
| `observe` | `screenshot`, `list_windows`, `get_active_window`, `window_info` | always on |
| `window` | `focus_window`, `move_resize_window`, `minimize_window`, `restore_window` | env-gated, off unless `DESKTOP_MCP_ENABLE_WINDOW=1` |
| `input` | `mouse_move`, `mouse_click`, `mouse_drag`, `mouse_scroll`, `key_press`, `hotkey`, `type_text` | env-gated, **OFF by default** -- requires `DESKTOP_MCP_ENABLE_INPUT=1` |
| `record` | `record_start`, `record_status`, `record_stop` | env-gated, off unless `DESKTOP_MCP_ENABLE_RECORD=1` |

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.

## Security

Read this before you register desktop-mcp. This is a desktop-control server;
what it can do to your machine is spelled out here plainly so you can make an
informed decision. Honesty about the blast radius is the point.

- **The `observe` group (`screenshot`, window enumeration) is ALWAYS ON and
  cannot be disabled.** Any caller that can reach this server can capture the
  contents of *any* visible window on the machine -- including a password
  manager, an authenticator/2FA app, a seed phrase, a banking tab, or a
  private message. `screenshot` returns a **file path to a PNG written to the
  scratch dir** (default `%TEMP%\desktop-mcp-scratch`), not inline pixels, so
  captured screen contents also persist on disk until that directory is
  cleared. Treat the scratch dir as sensitive and run this server only on a
  machine and under a harness you trust.
- **`DESKTOP_MCP_ENABLE_INPUT=1` grants keystroke and mouse injection into the
  focused window -- this is RCE-equivalent.** With the `input` group enabled,
  a caller can type commands, press hotkeys, and drive the mouse in whatever
  window currently has focus (a terminal, a browser, an admin tool). It is
  **OFF by default** for exactly this reason; turn it on only when you
  understand that you are handing the caller the keyboard. When disabled every
  input tool returns a structured `policy_refusal` (never a silent action).
- **Least privilege:** leave `input`, `window`, and `record` groups off unless
  a specific task needs them, keep this server on a trusted host, and do not
  run it elevated (admin) unless you have accepted that an elevated input group
  can drive elevated windows.

The env-gating, default-off input group, structured refusals, and rate cap
described above are the enforced controls; this section states, without
softening, what remains reachable by design.

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

| Claim | Implementation | Verified by |
|---|---|---|
| Capture a screenshot (monitor / region / window) as PNG | `desktop_mcp/groups/observe.py::screenshot` | `tests/test_observe.py::TestScreenshot`, live: `tests/test_live_smoke.py::test_live_screenshot_real_png` |
| Enumerate windows / get active window / look up by title | `desktop_mcp/groups/observe.py` | `tests/test_observe.py::TestListWindows`, `TestGetActiveWindow`, `TestWindowInfo` |
| Focus / move+resize / minimize / restore a window | `desktop_mcp/groups/window.py` | `tests/test_window.py` |
| Mouse move/click/drag/scroll, key press/hotkey, type text | `desktop_mcp/groups/input_tools.py` | `tests/test_input.py` (mocked pyautogui only -- see Limitations) |
| Screen recording via ffmpeg gdigrab, hard duration cap, graceful stop | `desktop_mcp/groups/record.py` | `tests/test_record.py`, live: `tests/test_live_smoke.py::test_live_record_real_mp4` |
| Input group OFF by default, structured refusal when disabled | `desktop_mcp/config.py::group_enabled`, `gated` | `tests/test_config.py::TestGroupEnabled`, `tests/test_input.py::TestGateDisabledByDefault` |
| Rate cap on input actions (default 60/min) | `desktop_mcp/config.py::TokenBucket`, `RateLimiterRegistry` | `tests/test_config.py::TestTokenBucket`, `tests/test_input.py::TestRateLimit` |
| DPI-awareness bootstrap (per-monitor-v2) so mss/pyautogui coords agree on scaled displays | `desktop_mcp/config.py::ensure_dpi_awareness` | `tests/test_config.py::TestDpiAwareness` (idempotency only; visual coord-agreement is not automated -- see Limitations) |
| Coordinate validation against virtual-desktop bounds before any mouse action | `desktop_mcp/groups/input_tools.py::_validate_point` | `tests/test_input.py` (out-of-bounds cases) |
| Orphan-guard: a stale recorder from a crashed process gets killed before a new one starts | `desktop_mcp/groups/record.py::_orphan_guard` | `tests/test_record.py::TestRecordStart::test_orphan_guard_kills_stale_recorder` |

## Limitations (read before relying on this)

- **UIPI (User Interface Privilege Isolation) -- protects window handles,
  not input.** A medium-integrity process (this server, unless you elevate
  it) cannot manipulate a *window* owned by a higher-integrity
  (elevated/admin) process: `focus_window`, `move_resize_window`,
  `minimize_window`, and `restore_window` go through `pygetwindow`'s
  window-handle APIs (`desktop_mcp/groups/window.py`), which Windows blocks
  under UIPI and which this server surfaces as a structured
  `window_action_failed` error naming UIPI, never a silent no-op.
  **Keyboard/mouse input tools ARE covered by UIPI too -- and worse, they
  fail silently.** `type_text`, `hotkey`, `key_press`, and the mouse actions
  (`desktop_mcp/groups/input_tools.py`) go through `pyautogui`, whose Windows
  backend actually calls the legacy `keybd_event`/`mouse_event` Win32
  functions (not `SendInput` -- `pyautogui` tried `SendInput` and reverted to
  the older calls; see `_pyautogui_win.py` in the installed package). Per
  Microsoft's own docs, UIPI applies to synthesized input generally:
  "[applications] are permitted to inject input only into applications that
  are at an equal or lesser integrity level" (MSDN `SendInput` reference),
  and critically, "neither `GetLastError` nor the return value will indicate
  the failure was caused by UIPI blocking." `keybd_event`/`mouse_event` are
  void-return legacy calls with no failure signal at all, so `pyautogui` (and
  this server) cannot detect a block even in principle: if an elevated
  window has focus, these tools report `{"ok": true}` while Windows silently
  discards the injected keystrokes/clicks -- no exception, no error field,
  nothing reaches the target. This is **worse** than the window-handle path
  above, which at least raises a structured `window_action_failed` error
  naming UIPI. There is no code-level bypass and no workaround short of
  running the server elevated (or not enabling the input group at all),
  which this project does not do or recommend. Operators should treat any
  elevated app that could plausibly have focus as **silently unreachable**
  by this server's input tools, not as a gap that lets them through.
  *Possible future enhancement (not implemented): detect the foreground
  window's integrity level before injecting and return a structured refusal
  instead of a false `{"ok": true}` -- tracked as a v2 idea, not a current
  capability.*
- **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-regi