CursorTouch/Windows-MCP

🪟 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

• 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

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

• Seamless Windows Integration
  Interacts natively with Windows UI elements, opens apps, controls windows, simulates user input, and more.

• Use Any LLM (Vision Optional) Unlike many automation tools, Windows-MCP doesn't rely on any traditional computer vision techniques or specific fine-tuned models; it works with any LLMs, reducing complexity and setup time.

• Rich Toolset for UI Automation
  Includes tools for basic keyboard, mouse operation and capturing window/UI state.

• Lightweight & Open-Source
  Minimal dependencies and easy setup with full source code available under MIT license.

• Customizable & Extendable
  Easily adapt or extend tools to suit your unique automation or AI integration needs.

• Real-Time Interaction
  Typical latency between actions (e.g., from one mouse click to the next) ranges from 0.2 to 0.5 secs, and may slightly vary based on the number of active applications and system load, also the inferencing speed of the llm.

• DOM Mode for Browser Automation
  Special use_dom=True mode for State-Tool that focuses exclusively on web page content, filtering out browser UI elements for cleaner, more efficient web automation. Supports Chrome, Edge, and Firefox (Firefox uses an IAccessible2 fallback since it doesn't expose RootWebArea via UIA).

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.

• 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 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",
        "<path to the windows-mcp directory>",
        "run",
        "windows-mcp",
        "serve"
      ]
    }
  }
}

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

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

{
  "mcpServers": {
    "windows-mcp": {
      "command": "C:\\Users\\<user>\\.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",
    "<path to the windows-mcp 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 "<path>" run windows-mcp serve

claude mcp add --transport stdio windows-mcp -- C:\Users\<user>\.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\<user>\.local\bin\uvx.exe windows-mcp serve"

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.

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.

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

Requires Authorization: Bearer your_token header on all requests.

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

Restricts connections to specified CIDR ranges. Blocks private/loopback IPs by default.

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.

All tools are enabled by default. Use --tools to whitelist specific tools, or --exclude-tools to block specific ones.

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

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

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://<host>: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

Dynamic client registration is disabled. Redirect URIs must be loopback http(s) only. Auth key and OAuth can coexist — both are accepted as valid Bearer tokens.

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

Desktop control is enabled by default. To run background tasks while using the computer yourself, disable it in ~/.windows-mcp/config.toml:

[control]
enabled = false
idle_timeout_seconds = 10.0

Or override it for one MCP server launch:

windows-mcp serve --no-control
windows-mcp serve --control --control-idle-timeout 3

In your MCP client's launch arguments, put these options after serve. The priority is CLI > environment variable > TOML > default. --control can explicitly override enabled = false. The timeout accepts finite positive seconds (including fractions); zero does not disable control. The default remains 10 seconds.

Restart the Windows-MCP server process after changing these settings. There is no hot reload or AI configuration tool. ControlStatus reports the effective enabled and idle_timeout_seconds values, with state disabled when control is off.

Disabling control turns off ownership gating, physical input protection, takeover monitoring, and the control indicator. Tools remain available and serialized, with injected key/button cleanup retained. AI desktop actions can then interfere with your own input; PowerShell scripts can also operate the UI. The separate screenshot flash setting is unchanged. When control is enabled, the idle timer restarts with physical input, so shortening it does not allow background calls while you keep using the computer.

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.

Scrape tool blocks: private IPs, loopback, link-local, credentials-in-URLs, non-HTTP schemes.

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

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.

If a physical key/button release event is missed, the input monitor checks residual holds after the configured idle wait. Five consecutive all-released samples, at least 100 ms apart, clear the stale records. New physical input or a reported held key/button resets confirmation. This is best-effort: a zero GetAsyncKeyState result counts as released even when Windows cannot provide the state; repeated sampling filters transient readings but cannot distinguish persistent query failure.

Example claude_desktop_config.json:

Local (no security):

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

Remote (with auth + IP allowlist + TLS):

{
  "mcpServers": {
    "windows-mcp": {
      "command": "uvx",
      "args": ["windows-mcp", "serve", "--transport", "sse", "--host", "0.0.0.0"],
      "env": {
        "WINDOWS_MCP_AUTH_KEY": "your_token",
        "WINDOWS_MCP_IP_ALLOWLIST": "203.0.113.0/24",
        "WINDOWS_MCP_SSL_CERTFILE": "/path/to/cert.pem",
        "WINDOWS_MCP_SSL_KEYFILE": "/path/to/key.pem"
      }
    }
  }
}

MCP Client can access the following tools to interact with Windows:

• Click: Click on the screen at the given coordinates.
• Type: Type text on an element (optionally clears existing text).
• Scroll: Scroll vertically or horizontally on the window or specific regions.
• Move: Move mouse pointer or drag (set drag=True) to coordinates. For deterministic drag, set from_loc=[x, y] with drag=True to press at an explicit start point and release at loc in one tool call. Optional duration adds bounded intermediate movement.
• Shortcut: Press keyboard shortcuts (Ctrl+c, Alt+Tab, etc).
• Wait: Pause for a defined duration.
• WaitFor: Wait until text, an active window, an element, or a focused element appears by polling UI state inside one tool call.
• ControlStatus: Read the desktop control owner and remaining user-idle wait. It stays available when user takeover blocks new tool calls. During AI control, a visible edge and cursor glow indicate ownership; moving the physical mouse substantially or pressing Ctrl+Alt+Shift+Backspace returns control to the user until 10 seconds of inactivity. During screenshot capture, the indicator is temporarily hidden and physical input is released; any physical input during this interval preempts AI control, although ControlStatus can briefly still report ai until that event is processed. Stepwise desktop input stops at its next checkpoint, but an already-running external command (for example PowerShell or an App launch) may continue after takeover; this control gate does not cancel processes or undo completed side effects. On a detected hook fault, injected keys and mouse buttons are released asynchronously, so physical input can briefly overlap a still-held AI key or button. Windows may also silently remove a low-level hook without notifying this process; periodic hook replacement reduces but does not eliminate that undetected window. User takeover is therefore best-effort, not a security boundary or a guarantee of exclusive control. Sessionless MCP 2026-07-28 clients cannot receive unsolicited control-state logs; they should query ControlStatus when they need the current owner.
• DisplayInventory: Read display layout, work areas, effective DPI, and scale metadata.
• Screenshot: Fast screenshot-first desktop capture with cursor position, active/open windows, and an image. Skips UI tree extraction for speed and should be the default first call when you mainly need visual context. Supports display=[0] or display=[0,1] using zero-based active Windows display indices, and region=[left, top, right, bottom] (virtual-desktop pixel coordinates) to capture just that rectangle instead of the whole screen — cheaper on tokens when you already know which area matters. region takes precedence over display when both are given; an invalid or out-of-bounds region raises an error. After capture, a brief orange-red glowing border is drawn inside the captured area as a visual confirmation (set WINDOWS_MCP_DISABLE_FLASH=1 to disable).
• Snapshot: Full desktop state capture for workflows that need interactive element ids, scrollable regions, or use_dom=True browser extraction. Supports use_vision=True for including screenshots, display=[0] or display=[0,1] using zero-based active Windows display indices, and region=[left, top, right, bottom] (virtual-desktop pixel coordinates) to inspect just that rectangle instead of the whole screen; region takes precedence over display when both are given, and an invalid or out-of-bounds region raises an error.
• App: Launch an application by Start Menu name or strictly by executable path with separated argv and optional cwd; resize, move, and switch between windows.
• PowerShell: To execute PowerShell commands.
• FileSystem: Read, write, copy, move, delete, list, search, and inspect files and directories.
• Scrape: To scrape the entire webpage for information.
• MultiSelect: Select multiple items (files, folders, checkboxes) with optional Ctrl key. Uses bulk label-to-coordinate resolution when labels are provided.
• MultiEdit: Enter text into multiple input fields at specified coordinates. Uses bulk label-to-coordinate resolution when labels are provided.
• Clipboard: Read or set Windows clipboard content.
• Process: List running processes or terminate them by PID or name.
• Notification: Send a Windows toast notification with a title and message.
• Registry: Read, write, delete, or list Windows Registry values and keys.

Stay updated and join our community:

• 📢 Follow us on X for the latest news and updates

• 💬 Join our Discord Community

Thanks to all the amazing people who have contributed to Windows-MCP! 🎉

We appreciate every contribution, whether it's code, documentation, bug reports, or feature suggestions. Want to contribute? Check out our Contributing Guidelines!

Important: Windows-MCP operates with full system access and can perform irreversible operations. Please review our comprehensive security guidelines before deployment.

For detailed security information, including:

• Tool-specific risk assessments
• Deployment recommendations
• Vulnerability reporting procedures
• Compliance and auditing guidelines

Please read our Security Policy.

Windows-MCP collects usage data to help improve the MCP server. No personal information, no tool arguments, no outputs are tracked.

To disable telemetry, set ANONYMIZED_TELEMETRY to false in your MCP client configuration:

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

See the Environment Variables section for the full list of configurable options.

For detailed information on what data is collected and how it is handled, please refer to the Telemetry and Data Privacy section in our Security Policy.

• Selecting specific sections of the text in a paragraph, as the MCP is relying on a11y tree. (⌛ Working on it.)
• Type-Tool is meant for typing text, not programming in IDE because of it types program as a whole in a file. (⌛ Working on it.)
• This MCP server can't be used to play video games 🎮.

This project is licensed under the MIT License - see the LICENSE file for details.

Windows-MCP makes use of several excellent open-source projects that power its Windows automation features:

• UIAutomation

Huge thanks to the maintainers and contributors of these libraries for their outstanding work and open-source spirit.

Contributions are welcome! Please see CONTRIBUTING for setup instructions and development guidelines.

Made with ❤️ by CursorTouch

@software{
  author       = {CursorTouch},
  title        = {Windows-MCP: Lightweight open-source project for integrating LLM agents with Windows},
  year         = {2024},
  publisher    = {GitHub},
  url={https://github.com/CursorTouch/Windows-MCP}
}