Desktop MCP

What desktop-mcp MCP server does

The desktop-mcp MCP server gives an MCP client access to selected Windows desktop operations. Its always-enabled observation group can capture a monitor, region, or window as a PNG, enumerate open windows, identify the active window, and look up window details by title. The returned screenshot is a file path in a scratch directory rather than inline image data.

Additional capabilities are divided into separate groups. Window tools can focus, move, resize, minimize, and restore windows. Input tools can move, click, drag, and scroll the mouse, press keys, send hotkeys, and type text. The recording group starts, reports, and stops ffmpeg-based screen recordings.

How it works

The package exposes a FastMCP server that communicates over stdio. Install it with pip, then register the desktop-mcp command in an MCP host configuration. A Python module invocation is also available when the host configuration uses python -m desktop_mcp.

Observation is available without an enable flag. Window management, input, and recording are independently controlled by environment variables. Disabled groups return structured policy_refusal errors. Input actions also pass through a rate limiter, set to 60 actions per minute by default, and over-limit requests return rate_limited errors.

The server initializes Windows DPI awareness and validates mouse coordinates against virtual-desktop bounds. Recording uses ffmpeg's Windows gdigrab mechanism and includes a duration cap, graceful stopping, and protection against a stale recorder left by a crashed process.

Setup and configuration

Install the package with:

pip install desktop-mcp

A stdio client can register it with a command such as:

{
  "mcpServers": {
    "desktop-mcp": {
      "command": "desktop-mcp"
    }
  }
}

Set DESKTOP_MCP_ENABLE_WINDOW=1, DESKTOP_MCP_ENABLE_INPUT=1, or DESKTOP_MCP_ENABLE_RECORD=1 to activate the corresponding optional group. Input remains disabled unless explicitly enabled. The input limit can be adjusted with DESKTOP_MCP_RATE_LIMIT_PER_MIN.

Tools and capabilities

The desktop-mcp MCP server organizes tools into these groups:

• observe: screenshot, list_windows, get_active_window, and window_info.
• window: focus, move or resize, minimize, and restore operations.
• input: mouse movement, clicks, drags, scrolling, key presses, hotkeys, and text entry.
• record: start, inspect, and stop screen recordings.

Limitations and notes

The observation group cannot be disabled. Any caller that can reach the server may capture visible content from any window, including sensitive applications. PNG files remain in the scratch directory, which defaults to %TEMP%\\desktop-mcp-scratch, until cleared.

Enabling input grants control of the focused window and should be treated as equivalent to handing the caller the keyboard and mouse. Run the desktop-mcp MCP server only under a trusted harness and host, leave unnecessary groups disabled, and avoid running it elevated unless the consequences are understood.

Windows User Interface Privilege Isolation can prevent window-handle operations against elevated applications; those failures are surfaced as structured errors. Injected mouse and keyboard actions targeting elevated windows may instead appear successful while Windows silently discards them. The project does not provide a bypass. Input behavior is tested with mocked pyautogui rather than every real elevated-window case, and DPI coordinate agreement is not fully verified by automated tests.