CursorTouch/Windows-MCP

Windows-MCP is a lightweight, open-source project that enables seamless integration between AI agents and the Windows operating system. Acting as an MCP server bridges the gap between LLMs and the Windows operating system, allowing agents to perform tasks such as file navigation, application control, UI interaction, QA testing, and more.

mcp-name: io.github.CursorTouch/Windows-MCP

Updates

• Windows-MCP reached 2M+ Users in Claude Desktop Extensiosn.
• Try out 🪟Windows-Use, an agent built using Windows-MCP.
• Windows-MCP is now available on PyPI (thus supports uvx windows-mcp)
• Windows-MCP is added to MCP Registry

Supported Operating Systems

• Windows 7
• Windows 8, 8.1
• Windows 10
• Windows 11

🎥 Demos

✨ Key Features

• Seamless Windows Integration

• Use Any LLM (Vision Optional)

• Rich Toolset for UI Automation

• Lightweight & Open-Source

• Customizable & Extendable

• Real-Time Interaction

• DOM Mode for Browser Automation

🛠️Installation

Note: When you install this MCP server for the first time it may take a minute or two because of installing the dependencies in pyproject.toml. In the first run the server may timeout ignore it and restart it.

Prerequisites

• Python 3.13+
• UV (Package Manager) from Astra, install with pip install uv or curl -LsSf https://astral.sh/uv/install.sh | sh
• English as the default language in Windows preferred else disable the App-Tool in the MCP Server for Windows with other languages.

Run at Login

Run the server directly when needed:

uvx windows-mcp serve
uvx windows-mcp serve --transport sse --host localhost --port 8000
uvx windows-mcp serve --transport streamable-http --host localhost --port 8000

Install it as a background task that starts now and at every login:

windows-mcp install
Or choose the HTTP transport and bind address explicitly
windows-mcp install --transport sse --host 127.0.0.1 --port 8000

This creates a per-user Scheduled Task named windows-mcp-server and a wrapper script at ~/.windows-mcp/start-server.cmd. Use windows-mcp uninstall to remove it. Logs are written to ~/.windows-mcp/server.log and ~/.windows-mcp/server.error.log.

npm install -g @anthropic-ai/mcpb

  {
    "mcpServers": {
      "windows-mcp": {
        "command": "uvx",
        "args": [
          "windows-mcp",
          "serve"
        ]
      }
    }
  }
  

  git clone https://github.com/CursorTouch/Windows-MCP.git
  cd Windows-MCP
  

  {
    "mcpServers": {
      "windows-mcp": {
        "command": "uv",
        "args": [
          "--directory",
          "",
          "run",
          "windows-mcp",
          "serve"
        ]
      }
    }
  }
  

  {
    "mcpServers": {
      "windows-mcp": {
        "command": "C:\\Users\\\\.local\\bin\\windows-mcp.exe",
        "args": ["serve"]
      }
    }
  }
  

  {
    "mcpServers": {
      "windows-mcp": {
        "command": "C:\\Users\\\\.local\\bin\\uvx.exe",
        "args": ["windows-mcp", "serve"]
      }
    }
  }
  

  {
    "mcpServers": {
      "windows-mcp": {
        "command": "C:\\Users\\\\.local\\bin\\uv.exe",
        "args": [
          "--directory",
          "C:\\path\\to\\Windows-MCP",
          "run",
          "windows-mcp",
          "serve"
        ]
      }
    }
  }
  

  {
    "command": "uvx",
    "args": [
      "windows-mcp",
      "serve"
    ]
  }
  

  {
    "command": "uv",
    "args": [
      "--directory",
      "",
      "run",
      "windows-mcp",
      "serve"
    ]
  }
  

npm install -g @google/gemini-cli

{
  "theme": "Default",
  ...
  "mcpServers": {
    "windows-mcp": {
      "command": "uvx",
      "args": [
        "windows-mcp",
        "serve"
      ]
    }
  }
}

npm install -g @qwen-code/qwen-code@latest

{
  "mcpServers": {
    "windows-mcp": {
      "command": "uvx",
      "args": [
        "windows-mcp",
        "serve"
      ]
    }
  }
}

npm install -g @openai/codex

[mcp_servers.windows-mcp]
command="uvx"
args=[
  "windows-mcp",
  "serve"
]

  autohand mcp add windows-mcp uvx windows-mcp serve
  

npm install -g @anthropic-ai/claude-code

  claude mcp add --transport stdio windows-mcp -- uvx windows-mcp serve
  

  git clone https://github.com/CursorTouch/Windows-MCP.git
  cd Windows-MCP
  

  claude mcp add --transport stdio windows-mcp -- uv --directory "" run windows-mcp serve
  

  claude mcp add --transport stdio windows-mcp -- C:\Users\\.local\bin\uvx.exe windows-mcp serve
  

  irm https://astral.sh/uv/install.ps1 | iex
  

  claude mcp add windows-mcp --transport stdio -s user -- powershell.exe -Command "C:\Users\\.local\bin\uvx.exe windows-mcp serve"
  

---

🖥️ Running Windows-MCP

Windows-MCP runs directly on your Windows machine and exposes its tools to the connected MCP client.

# 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

Optional environment variables can be set to customize behavior — see Environment Variables below.

Security for Remote Access

For network access, enable authentication and TLS:

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

See 🔐 Security & Access Control for all options.

Transport Options

| Transport | Command | Use Case | |---|---|---| | stdio (default) | serve --transport stdio | Direct connection from MCP clients like Claude Desktop, Cursor, etc. | | sse | serve --transport sse --host HOST --port PORT | Network-accessible via Server-Sent Events | | streamable-http | serve --transport streamable-http --host HOST --port PORT | Network-accessible via HTTP streaming (recommended for production) |

---

🔐 Security & Access Control

Authentication

windows-mcp serve --transport sse --host 0.0.0.0 --auth-key "your_token"

IP Allowlist

windows-mcp serve --auth-key "token" --ip-allowlist "203.0.113.0/24,198.51.100.5"

CORS Origins

By default, no CORS headers are emitted. Browsers block cross-origin requests via their own Same-Origin Policy, which means arbitrary websites cannot reach the MCP control plane even if the server is on localhost. Host-header validation (DNS rebinding protection) is also applied automatically based on the bind address.

If you need a browser-based MCP client to reach the server, opt in with an explicit origin allowlist:

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

Only the listed origins receive Access-Control-Allow-Origin headers; all other cross-origin requests are rejected by the browser. The equivalent environment variable is WINDOWS_MCP_CORS_ORIGINS.

Tool Selection

windows-mcp serve --tools "Screenshot,Click,Snapshot"   # Enable only these tools
windows-mcp serve --exclude-tools "PowerShell,Registry" # Disable specific tools

TLS/HTTPS

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes
windows-mcp serve --ssl-certfile cert.pem --ssl-keyfile key.pem

OAuth 2.0 + PKCE

For MCP clients that use OAuth (e.g. Claude Desktop) instead of a static API key:

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 config:

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

The OAuth server exposes:

• GET /.well-known/oauth-authorization-server — server metadata (RFC 8414)
• GET /oauth/authorize — Authorization Code + PKCE (S256 required)
• POST /oauth/token — token exchange (client secret required)
• POST /oauth/register — disabled; clients must be pre-provisioned

Config File (~/.windows-mcp/config.toml)

Instead of passing flags every time, store your configuration in ~/.windows-mcp/config.toml. CLI flags always override config file values.

Search order: 1. --config /path/to/config.toml 2. ~/.windows-mcp/config.toml

stdio — local only, no security needed:

[server]
transport = "stdio"

SSE — network access with auth and IP restriction:

[server]
transport = "sse"
host      = "0.0.0.0"
port      = 8000
auth_key  = "your-secret-key"

[security]
ip_allowlist = ["192.168.1.0/24"]

Streamable HTTP — with auth, TLS, and tool exclusions:

[server]
transport    = "streamable-http"
host         = "0.0.0.0"
port         = 8000
auth_key     = "your-secret-key"
ssl_certfile = "cert.pem"   # resolved relative to ~/.windows-mcp/
ssl_keyfile  = "key.pem"

[security]
ip_allowlist        = ["192.168.1.0/24"]
cors_origins        = ["https://my-client.example.com"]   # optional — browser CORS opt-in
oauth_client_id     = "my-client"      # optional — enables OAuth 2.0 + PKCE
oauth_client_secret = "my-secret"
[tools]
exclude = ["PowerShell", "Registry"]   # disable specific tools

Place cert and key files in the same directory:

~/.windows-mcp/
├── config.toml
├── cert.pem
└── key.pem

Generate a self-signed cert directly into that directory:

mkdir -p ~/.windows-mcp
openssl req -x509 -newkey rsa:4096 \
  -keyout ~/.windows-mcp/key.pem \
  -out ~/.windows-mcp/cert.pem \
  -days 365 -nodes

auth Helper

Generate an auth key and save a working config to ~/.windows-mcp/config.toml:

windows-mcp auth

Generate auth plus a self-signed TLS certificate:

windows-mcp auth --transport streamable-http --host 0.0.0.0 --port 8000 --with-tls

This command writes the auth key into the config file, can generate cert.pem and key.pem, and prints an example MCP client configuration for the selected transport.

SSRF Protection

---

⚙️ Environment Variables

All variables are optional unless noted. Set them via the env key in claude_desktop_config.json (or your MCP client's equivalent config).

Screenshot & Snapshot

| Variable | Default | Description | |---|---|---| | WINDOWS_MCP_SCREENSHOT_SCALE | 1.0 | Scale factor applied to screenshots before encoding. Accepts a float in the range 0.1–1.0. Useful on high-resolution displays (1440p, 4K) where the default produces images that exceed Claude Desktop's 1 MB tool-result limit. Set to 0.5 to halve both dimensions (quarter the file size). | | WINDOWS_MCP_SCREENSHOT_BACKEND | auto | Screenshot capture backend. Accepted values: auto (tries dxcam → mss → pillow in order), dxcam, mss, pillow. Use mss or pillow if dxcam is unavailable or causes issues on your GPU. | | WINDOWS_MCP_PROFILE_SNAPSHOT | _(disabled)_ | Set to 1, true, yes, or on to emit per-stage timing logs for Screenshot/Snapshot calls. Useful for diagnosing slow captures. | | WINDOWS_MCP_DISABLE_FLASH | _(disabled)_ | Set to 1, true, yes, or on to suppress the orange-red glowing border that briefly highlights the captured area after every screenshot. The flash is rendered on a transparent always-on-top window after capture so it never appears in the captured image. |

Excluding processes from UI Automation traversal

| Variable | Default | Description | |---|---|---| | WINDOWS_MCP_EXCLUDE_PROCESSES | _(none)_ | Comma-separated process basenames whose windows are excluded from UI Automation tree traversal, e.g. Code.exe,Cursor.exe. Matching is case-insensitive and exact — no wildcards or regular expressions. Unset or empty preserves current behaviour. |

Some applications expose accessibility trees that can become slow or unresponsive during UI Automation traversal. Snapshot and WaitFor may traverse the active window and other top-level handles selected for tree capture, so one pathological accessibility provider can stall the capture.

Set:

WINDOWS_MCP_EXCLUDE_PROCESSES=Code.exe,Cursor.exe

Process names are comma-separated executable basenames. They are matched case-insensitively after surrounding whitespace is stripped; empty entries are ignored and duplicates are harmless.

A window is excluded before any UI Automation call is made against it, so its accessibility provider is never entered. Excluded applications may still appear in the window list, but Windows-MCP will not traverse their accessibility trees, and they are not reported as failed captures. If the owning process of a window cannot be resolved, the window is traversed as usual.

This is an exclusion mechanism — a mitigation, not a complete fix for every form of #383. It only skips the processes you name; a pathological window you have not listed can still stall a capture.

Security

| Variable | Default | Description | |---|---|---| | WINDOWS_MCP_AUTH_KEY | _(none)_ | Bearer token required on all HTTP requests. Alternative to --auth-key CLI flag. | | WINDOWS_MCP_IP_ALLOWLIST | _(none)_ | Comma-separated list of allowed client IPs or CIDR ranges (e.g., 203.0.113.0/24,198.51.100.5). Alternative to --ip-allowlist CLI flag. | | WINDOWS_MCP_CORS_ORIGINS | _(none)_ | Comma-separated list of origins permitted to make cross-origin browser requests (e.g., https://my-client.example.com). No CORS headers are emitted when unset. Alternative to --cors-origins CLI flag. | | WINDOWS_MCP_TOOLS | _(all enabled)_ | Comma-separated explicit list of tools to enable (e.g., Screenshot,Click,Snapshot). Alternative to --tools CLI flag. | | WINDOWS_MCP_EXCLUDE_TOOLS | _(none)_ | Comma-separated list of tools to disable (e.g., PowerShell,Registry). Alternative to --exclude-tools CLI flag. | | WINDOWS_MCP_SSL_CERTFILE | _(none)_ | Path to TLS certificate file (.pem) for HTTPS. Must be provided with WINDOWS_MCP_SSL_KEYFILE. | | WINDOWS_MCP_SSL_KEYFILE | _(none)_ | Path to TLS private key file (.pem) for HTTPS. Must be provided with WINDOWS_MCP_SSL_CERTFILE. | | WINDOWS_MCP_OAUTH_CLIENT_ID | _(none)_ | OAuth client ID for HTTP transports. Must be provided with WINDOWS_MCP_OAUTH_CLIENT_SECRET. | | WINDOWS_MCP_OAUTH_CLIENT_SECRET | _(none)_ | OAuth client secret for HTTP transports. Must be provided with WINDOWS_MCP_OAUTH_CLIENT_ID. | | WINDOWS_MCP_STATELESS_HTTP | false | Set to 1, true, yes, or on to run streamable-http without Mcp-Session-Id connection state. Useful for rec