Labsco
CursorTouch logo

Windows-MCP

★ 6,300

from CursorTouch

A lightweight MCP server for interacting with the Windows Operating System.

🔥🔥🔥🔥✓ VerifiedFreeAdvanced setup
#automation#analytics#scraping#browser#documents#devops#git#search

🪟 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

Supported Operating Systems

  • Windows 7

  • Windows 8, 8.1

  • Windows 10

  • Windows 11

🎥 Demos

https://github.com/user-attachments/assets/d0e7ed1d-6189-4de6-838a-5ef8e1cad54e

https://github.com/user-attachments/assets/d2b372dc-8d00-4d71-9677-4c64f5987485

✨ Key Features

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).

🔐 Security & Access Control

Authentication

Copy & paste — that's it
windows-mcp serve --transport sse --host 0.0.0.0 --auth-key "your_token"

Requires Authorization: Bearer your_token header on all requests.

IP Allowlist

Copy & paste — that's it
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.

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:

Copy & paste — that's it
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

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

Copy & paste — that's it
windows-mcp serve --tools "Screenshot,Click,Snapshot" # Enable only these tools
windows-mcp serve --exclude-tools "PowerShell,Registry" # Disable specific tools

TLS/HTTPS

Copy & paste — that's it
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:

Copy & paste — that's it
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:

Copy & paste — that's it
{
 "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

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.

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:

  • --config /path/to/config.toml

  • ~/.windows-mcp/config.toml

stdio — local only, no security needed:

Copy & paste — that's it
[server]
transport = "stdio"

SSE — network access with auth and IP restriction:

Copy & paste — that's it
[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:

Copy & paste — that's it
[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:

Copy & paste — that's it
~/.windows-mcp/
├── config.toml
├── cert.pem
└── key.pem

Generate a self-signed cert directly into that directory:

Copy & paste — that's it
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:

Copy & paste — that's it
windows-mcp auth

Generate auth plus a self-signed TLS certificate:

Copy & paste — that's it
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

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

⚙️ 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.

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 reconnects after restarts and for horizontally scaled deployments.

Telemetry

Variable Default Description ANONYMIZED_TELEMETRY true Set to false to disable anonymous usage telemetry. No personal data, tool arguments, or outputs are ever collected regardless of this setting. POSTHOG_API_KEY Project default Override the PostHog project write key used for anonymous telemetry. Set to an empty string to skip PostHog client initialization. POSTHOG_HOST https://us.i.posthog.com Override the PostHog host for anonymous telemetry, such as for a self-hosted PostHog deployment.

Debug

Variable Default Description WINDOWS_MCP_DEBUG false Set to 1, true, yes, or on to enable debug mode, which sets the log level to DEBUG for verbose output. Also available as the --debug CLI flag.

Example claude_desktop_config.json:

Local (no security):

Copy & paste — that's it
{
 "mcpServers": {
 "windows-mcp": {
 "command": "uvx",
 "args": ["windows-mcp", "serve"],
 "env": { "WINDOWS_MCP_SCREENSHOT_SCALE": "0.5" }
 }
 }
}

Remote (with auth + IP allowlist + TLS):

Copy & paste — that's it
{
 "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 Tools

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.

  • 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.

  • 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. 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 and display=[0] or display=[0,1] using zero-based active Windows display indices.

  • App: To launch an application from the start menu, resize or move the window and switch between apps.

  • 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.

🤝 Connect with Us

Stay updated and join our community:

📢 Follow us on X for the latest news and updates

💬 Join our Discord Community

Star History

👥 Contributors

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!

🔒 Security

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.

📊 Telemetry

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:

Copy & paste — that's it
{
 "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.

🪪 License

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

🙏 Acknowledgements

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

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

🤝Contributing

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

Made with ❤️ by CursorTouch

Citation

Copy & paste — that's it
@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}
}