Windows-MCP

Windows-MCP is a lightweight, open-source MCP (Model Context Protocol) server that enables AI agents to interact with the Windows operating system. It bridges the gap between LLMs and Windows, allowing agents to perform tasks like file navigation, application control, UI interaction, and QA testing.

Key Details:

• MCP Name: io.github.CursorTouch/Windows-MCP
• Supported OS: Windows 7, 8, 8.1, 10, and 11.
• Core Capabilities: Native Windows UI interaction, application control, keyboard/mouse simulation, and window state capture.
• LLM Compatibility: Works with any LLM as it does not rely on traditional computer vision; it uses UI automation techniques instead.
• Browser Automation: Includes a DOM Mode for the State-Tool (via use_dom=True) which focuses on web page content for Chrome, Edge, and Firefox (Firefox uses an IAccessible2 fallback).

When building agents that use Windows-MCP, follow these best practices for reliability:

• Visual Context: Use win_snapshot before interacting with any visible application to understand the UI state.
• Element Interaction: Prefer using element labels or IDs returned by win_snapshot when calling win_click, win_type, win_move, or win_scroll.
• Fallback to Coordinates: Use screen coordinates only when labels/IDs are unavailable or ambiguous.
• Keyboard Workflows: Use win_shortcut for system-level or application-level shortcuts (e.g., ctrl+l, ctrl+c, alt+tab, or win+r).
• Visual Inspection: Use win_screenshot for quick visual checks when you do not need structured UI element data.
• Browser Automation: When interacting with web content, use use_dom=true with win_snapshot to target the browser page content instead of the browser UI elements.

When exposing the server over a network using sse transport, you should enable authentication and TLS to secure the connection.

Use the following flags:

• --auth-key: A secret token for authentication.
• --ip-allowlist: A list of allowed IP addresses/ranges (e.g., 203.0.113.0/24).
• --ssl-certfile: Path to your SSL certificate file.
• --ssl-keyfile: Path to your SSL key file.

windows-mcp serve --transport sse --host 0.0.0.0 \
  --auth-key "your_secret_token" \
  --ip-allowlist "203.0.113.0/24" \
  --ssl-certfile cert.pem --ssl-keyfile key.pem

You can install Windows-MCP globally in Pi using a single command. This installs the package and exposes Pi-native tools that forward to the underlying MCP tools.

pi install git:github.com/CursorTouch/Windows-MCP

By default, no CORS headers are emitted. If you need a browser-based MCP client to reach the server, you must explicitly allow origins using the --cors-origins flag or the WINDOWS_MCP_CORS_ORIGINS environment variable. Only the listed origins will receive Access-Control-Allow-Origin headers.

windows-mcp serve --cors-origins "https://my-client.example.com,https://other.example.com"

When an agent needs visual context, use the following tools:

• Screenshot: Best for fast desktop capture. It skips UI tree extraction for speed. Supports display=[index] (e.g., display=[0] or display=[0,1]) using zero-based Windows display indices. Note: A brief orange-red glowing border is drawn around the captured area unless WINDOWS_MCP_DISABLE_FLASH=1 is set.
• Snapshot: Best for workflows requiring interactive element IDs, scrollable regions, or browser extraction via use_dom=True. Supports use_vision=True to include screenshots and display=[index] for specific monitors.

All tools are enabled by default. You can control tool availability using the --tools flag (to whitelist only specific tools) or the --exclude-tools flag (to block specific tools).

# Enable only these tools
windows-mcp serve --tools "Screenshot,Click,Snapshot"

# Disable specific tools
windows-mcp serve --exclude-tools "PowerShell,Registry"

You can run the server directly using uvx. By default, it uses stdio transport. For network access, you can specify sse or streamable-http transports along with a host and port.

Note: On the first run, dependency installation via pyproject.toml may take a few minutes. If the server times out during this initial setup, simply restart it.

# Runs with stdio transport (default)
uvx windows-mcp serve

# Or with SSE/Streamable HTTP for network access
uvx windows-mcp serve --transport sse --host localhost --port 8000
uvx windows-mcp serve --transport streamable-http --host localhost --port 8000

For clients like Claude Desktop that support OAuth, run the server with the streamable-http transport and provide OAuth credentials. The server implements RFC 8414 metadata and requires S256 for PKCE.

# Server command
windows-mcp serve --transport streamable-http --host 0.0.0.0 \
  --ssl-certfile ~/.windows-mcp/cert.pem \
  --ssl-keyfile  ~/.windows-mcp/key.pem \
  --oauth-client-id my-client \
  --oauth-client-secret my-secret

Claude Desktop Configuration:

{
  "mcpServers": {
    "windows-mcp": {
      "type": "http",
      "url": "https://<host>:8000/mcp/",
      "oauth": {
        "clientId": "my-client",
        "clientSecret": "my-secret"
      }
    }
  }
}

Before installing windows-mcp, ensure your system meets the following requirements:

• Python: 3.13 or higher.
• UV (Package Manager): Install via pip install uv or curl -LsSf https://astral.sh/uv/install.sh | sh.
• Language: Windows preferred language should be English. If using other languages, you must disable the App-Tool in the MCP Server for Windows.