{
  "markdown": "# desktop-mcp\n\n[![PyPI](https://img.shields.io/pypi/v/desktop-mcp)](https://pypi.org/project/desktop-mcp/)\n[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-io.github.jaimenbell%2Fdesktop--mcp-blue)](https://registry.modelcontextprotocol.io)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n[![tests](https://img.shields.io/badge/tests-141%20%28139%20passing%2C%202%20skipped%29-brightgreen)](tests)\n[![CI](https://github.com/jaimenbell/desktop-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/jaimenbell/desktop-mcp/actions/workflows/ci.yml)\n\nWindows desktop-control MCP server: screenshot, window management,\nmouse/keyboard input, and ffmpeg screen-recording, config-gated by tool\ngroup (**input off by default**) -- built to the same standard as\n[mcp-factory](https://github.com/jaimenbell/mcp-factory) and rag-mcp: own\npyproject, fastmcp server, honest README, real test suite.\n\n## Quickstart\n\n```bash\npip install desktop-mcp\n```\n\n```jsonc\n// ~/.claude.json (or any MCP-host stdio client config)\n{\n  \"mcpServers\": {\n    \"desktop-mcp\": {\n      \"command\": \"desktop-mcp\"\n      // or: \"command\": \"python\", \"args\": [\"-m\", \"desktop_mcp\"]\n    }\n  }\n}\n```\n\n`window`/`input`/`record` tool groups are env-gated -- `input` stays off\nunless you explicitly opt in. See Env vars below for the full table.\n\n## Tool groups\n\n| Group | Tools | Default state |\n|---|---|---|\n| `observe` | `screenshot`, `list_windows`, `get_active_window`, `window_info` | always on |\n| `window` | `focus_window`, `move_resize_window`, `minimize_window`, `restore_window` | env-gated, off unless `DESKTOP_MCP_ENABLE_WINDOW=1` |\n| `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` |\n| `record` | `record_start`, `record_status`, `record_stop` | env-gated, off unless `DESKTOP_MCP_ENABLE_RECORD=1` |\n\nA disabled group returns a structured `policy_refusal` error (never a silent\nno-op, never a crash). Input actions are additionally rate-capped (default 60\nactions/min, tunable via `DESKTOP_MCP_RATE_LIMIT_PER_MIN`) -- exceeding the\ncap returns a structured `rate_limited` error.\n\nThis is defense-in-depth: harness-level permission prompts are the first\ngate, but the server itself refuses input/window/record actions unless its\nown env explicitly enables them, so a misconfigured or overly-permissive\nharness can't turn on capabilities the operator didn't opt into for this\nprocess.\n\n## Security\n\nRead this before you register desktop-mcp. This is a desktop-control server;\nwhat it can do to your machine is spelled out here plainly so you can make an\ninformed decision. Honesty about the blast radius is the point.\n\n- **The `observe` group (`screenshot`, window enumeration) is ALWAYS ON and\n  cannot be disabled.** Any caller that can reach this server can capture the\n  contents of *any* visible window on the machine -- including a password\n  manager, an authenticator/2FA app, a seed phrase, a banking tab, or a\n  private message. `screenshot` returns a **file path to a PNG written to the\n  scratch dir** (default `%TEMP%\\desktop-mcp-scratch`), not inline pixels, so\n  captured screen contents also persist on disk until that directory is\n  cleared. Treat the scratch dir as sensitive and run this server only on a\n  machine and under a harness you trust.\n- **`DESKTOP_MCP_ENABLE_INPUT=1` grants keystroke and mouse injection into the\n  focused window -- this is RCE-equivalent.** With the `input` group enabled,\n  a caller can type commands, press hotkeys, and drive the mouse in whatever\n  window currently has focus (a terminal, a browser, an admin tool). It is\n  **OFF by default** for exactly this reason; turn it on only when you\n  understand that you are handing the caller the keyboard. When disabled every\n  input tool returns a structured `policy_refusal` (never a silent action).\n- **Least privilege:** leave `input`, `window`, and `record` groups off unless\n  a specific task needs them, keep this server on a trusted host, and do not\n  run it elevated (admin) unless you have accepted that an elevated input group\n  can drive elevated windows.\n\nThe env-gating, default-off input group, structured refusals, and rate cap\ndescribed above are the enforced controls; this section states, without\nsoftening, what remains reachable by design.\n\n## Honest-capabilities table\n\nEvery claim below maps to the file that implements it and the test(s) that\nverify it -- no capability is asserted without a corresponding\nimplementation + test.\n\n| Claim | Implementation | Verified by |\n|---|---|---|\n| 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` |\n| Enumerate windows / get active window / look up by title | `desktop_mcp/groups/observe.py` | `tests/test_observe.py::TestListWindows`, `TestGetActiveWindow`, `TestWindowInfo` |\n| Focus / move+resize / minimize / restore a window | `desktop_mcp/groups/window.py` | `tests/test_window.py` |\n| 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) |\n| 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` |\n| 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` |\n| Rate cap on input actions (default 60/min) | `desktop_mcp/config.py::TokenBucket`, `RateLimiterRegistry` | `tests/test_config.py::TestTokenBucket`, `tests/test_input.py::TestRateLimit` |\n| 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) |\n| 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) |\n| 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` |\n\n## Limitations (read before relying on this)\n\n- **UIPI (User Interface Privilege Isolation) -- protects window handles,\n  not input.** A medium-integrity process (this server, unless you elevate\n  it) cannot manipulate a *window* owned by a higher-integrity\n  (elevated/admin) process: `focus_window`, `move_resize_window`,\n  `minimize_window`, and `restore_window` go through `pygetwindow`'s\n  window-handle APIs (`desktop_mcp/groups/window.py`), which Windows blocks\n  under UIPI and which this server surfaces as a structured\n  `window_action_failed` error naming UIPI, never a silent no-op.\n  **Keyboard/mouse input tools ARE covered by UIPI too -- and worse, they\n  fail silently.** `type_text`, `hotkey`, `key_press`, and the mouse actions\n  (`desktop_mcp/groups/input_tools.py`) go through `pyautogui`, whose Windows\n  backend actually calls the legacy `keybd_event`/`mouse_event` Win32\n  functions (not `SendInput` -- `pyautogui` tried `SendInput` and reverted to\n  the older calls; see `_pyautogui_win.py` in the installed package). Per\n  Microsoft's own docs, UIPI applies to synthesized input generally:\n  \"[applications] are permitted to inject input only into applications that\n  are at an equal or lesser integrity level\" (MSDN `SendInput` reference),\n  and critically, \"neither `GetLastError` nor the return value will indicate\n  the failure was caused by UIPI blocking.\" `keybd_event`/`mouse_event` are\n  void-return legacy calls with no failure signal at all, so `pyautogui` (and\n  this server) cannot detect a block even in principle: if an elevated\n  window has focus, these tools report `{\"ok\": true}` while Windows silently\n  discards the injected keystrokes/clicks -- no exception, no error field,\n  nothing reaches the target. This is **worse** than the window-handle path\n  above, which at least raises a structured `window_action_failed` error\n  naming UIPI. There is no code-level bypass and no workaround short of\n  running the server elevated (or not enabling the input group at all),\n  which this project does not do or recommend. Operators should treat any\n  elevated app that could plausibly have focus as **silently unreachable**\n  by this server's input tools, not as a gap that lets them through.\n  *Possible future enhancement (not implemented): detect the foreground\n  window's integrity level before injecting and return a structured refusal\n  instead of a false `{\"ok\": true}` -- tracked as a v2 idea, not a current\n  capability.*\n- **DPI scaling.** The server sets per-monitor-v2 DPI awareness at startup so\n  `mss` pixel coordinates and `pyautogui` point coordinates should agree on\n  scaled displays. This bootstrap is unit-tested for idempotency/no-crash\n  only -- actual coordinate agreement on a live multi-DPI multi-monitor setup\n  has not been automated-tested and should be spot-checked if you're\n  targeting a non-100%-scaled monitor.\n- **UAC secure desktop.** When Windows switches to the secure desktop (UAC\n  elevation prompts, Ctrl+Alt+Del, lock screen), no process running on the\n  regular desktop -- including this server -- can see or interact with it.\n  Screenshots will show whatever was on the regular desktop before the\n  switch; input calls will not reach the secure desktop at all.\n- **Single machine, local only.** No network transport, no remote control.\n  stdio only, spawned by the MCP host on the same machine.\n- **Input group is off by default in this repo's own registration.** See\n  `~/.claude.json`'s `desktop-mcp` entry -- `DESKTOP_MCP_ENABLE_INPUT` is not\n  set there. Enabling it is a deliberate per-registration operator choice,\n  not a code change.\n- **pyautogui failsafe.** `FAILSAFE=True` is intentional: slamming the cursor\n  into a screen corner mid-action raises inside pyautogui and aborts the\n  call. This can interrupt an in-flight `mouse_drag`. Treated as acceptable\n  v1 behavior (see plan's Open questions) -- it's a deliberate human\n  kill-switch, not a bug.\n- **No OCR / vision analysis.** Screenshots are raw PNGs; interpreting their\n  content is the consumer's job, not this server's.\n- **No clipboard tools.** Credential-adjacent surface, deferred to a v2 with\n  its own safety design.\n- **Not registered with the mcp-factory hub.** This ships as a standalone\n  repo (own pyproject, own venv-free system-Python312 install), matching the\n  rag-mcp model. Hub/registry integration is a v2 candidate.\n\n## Env vars\n\n| Var | Effect | Default |\n|---|---|---|\n| `DESKTOP_MCP_ENABLE_WINDOW` | enable the `window` tool group | unset (off) |\n| `DESKTOP_MCP_ENABLE_INPUT` | enable the `input` tool group | unset (off) |\n| `DESKTOP_MCP_ENABLE_RECORD` | enable the `record` tool group | unset (off) |\n| `DESKTOP_MCP_RATE_LIMIT_PER_MIN` | input-group rate cap | `60` |\n| `DESKTOP_MCP_SCRATCH_DIR` | where screenshots/recordings/pidfiles are written | `%TEMP%\\desktop-mcp-scratch` |\n| `DESKTOP_MCP_LIVE` | `1` to run real-hardware smoke tests (see Testing) | unset (skip) |\n\n## Usage examples\n\n```jsonc\n// A tool call from the MCP host, illustrative -- not a shell command.\n{\"tool\": \"screenshot\", \"arguments\": {\"monitor\": 0}}\n// -> {\"ok\": true, \"path\": \"C:\\\\Users\\\\...\\\\Temp\\\\desktop-mcp-scratch\\\\screenshot-....png\", \"w\": 3840, \"h\": 1080, \"monitor\": 0}\n\n{\"tool\": \"record_start\", \"arguments\": {\"fps\": 30, \"max_duration_s\": 30}}\n// -> {\"ok\": true, \"path\": \"...\\\\recording-....mp4\", \"pid\": 12345, \"fps\": 30, \"max_duration_s\": 30}\n{\"tool\": \"record_stop\", \"arguments\": {}}\n// -> {\"ok\": true, \"path\": \"...\\\\recording-....mp4\", \"bytes\": 800560, \"duration_s\": 3.13}\n\n// input group disabled (default):\n{\"tool\": \"mouse_click\", \"arguments\": {\"x\": 500, \"y\": 500}}\n// -> {\"ok\": false, \"error\": {\"type\": \"policy_refusal\", \"group\": \"input\", \"required_env\": \"DESKTOP_MCP_ENABLE_INPUT\", ...}}\n```\n\n## Testing\n\nCI (`.github/workflows/ci.yml`) runs this suite on every push/PR (on\n`windows-latest`, since `pywin32`/`PyGetWindow` are Windows-only deps that\ndon't install on Linux runners) and fails the build if the Tests badge\nabove drifts from what the suite actually reports -- see\n`scripts/check_readme_counts.py`.\n\n```\n# unit suite (mocked backends, no real screen/input/recording touched)\npython -m pytest -q\n\n# handshake check -- prints every registered tool name\npython scripts/list_tools.py\n\n# real-hardware smokes (real screenshot PNG, real ~3s screen recording;\n# never input-injection -- see safety rails above)\nDESKTOP_MCP_LIVE=1 python -m pytest -q -k live_screenshot\nDESKTOP_MCP_LIVE=1 python -m pytest -q -k live_record\n```\n\n## Install\n\n```\npip install -r requirements.txt   # or: pip install .\n# deps: fastmcp==3.4.2, mss==10.2.0, pyautogui==0.9.54, PyGetWindow==0.0.9, pywin32==312\n# also requires ffmpeg + ffprobe on PATH for the record group\n```\n\nRegistered in `~/.claude.json` as `desktop-mcp` (stdio, system Python312,\n`observe`+`window`+`record` groups enabled, `input` group absent from env).\n\n\n## Commercial support\n\nMaintained by [Jaimen Bell](https://jaimenbell.dev). For production MCP integrations, custom servers, or agent-reliability work, see [jaimenbell.dev](https://jaimenbell.dev).\n\nBuilding your own MCP server? The [MCP Starter Kit](https://jaimenbell.gumroad.com/l/adnojp) has templates, a build playbook, and packaging war-stories from shipping this one.\n\n<!-- MCP registry ownership marker -->\nmcp-name: io.github.jaimenbell/desktop-mcp\n",
  "bytes": 13912,
  "sha": "46034e6cbad26d7414e6984e64ea627824479566467fd597ebca145348b6ffdc",
  "repo_slug": "jaimenbell/desktop-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_jaimenbell_desktop_mcp_2198bcbd/readme"
}