🪟 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

Added VM support for Windows-MCP. Check (windowsmcp.io)[https://windowsmcp.io/] for more details.
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

windows.mcp.mov

✨ 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.9 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.

🛠️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.
(Optional) OCR Support — To use the use_ocr=True option in the Snapshot tool, install Tesseract OCR:
```
winget install UB-Mannheim.TesseractOCR
```

Install in Claude Desktop

Install Claude Desktop and

npm install -g @anthropic-ai/mcpb

Configure the extension:

Option A: Install from PyPI (Recommended)

Use uvx to run the latest version directly from PyPI.

Add this to your claude_desktop_config.json:

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

Option B: Install from Source

Clone the repository:

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

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "windows-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "<path to the windows-mcp directory>",
        "run",
        "windows-mcp"
      ]
    }
  }
}

Open Claude Desktop and enjoy! 🥳
Enjoy 🥳.

For additional Claude Desktop integration troubleshooting, see the MCP documentation. The documentation includes helpful tips for checking logs and resolving common issues.

Install in Perplexity Desktop

Install Perplexity Desktop:
Clone the repository.

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

cd Windows-MCP

Open Perplexity Desktop:

Go to Settings->Connectors->Add Connector->Advanced

Enter the name as Windows-MCP, then paste the following JSON in the text area.

Option A: Install from PyPI (Recommended)

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

Option B: Install from Source

{
  "command": "uv",
  "args": [
    "--directory",
    "<path to the windows-mcp directory>",
    "run",
    "windows-mcp"
  ]
}

Click Save and Enjoy 🥳.

For additional Claude Desktop integration troubleshooting, see the Perplexity MCP Support. The documentation includes helpful tips for checking logs and resolving common issues.

Install in Gemini CLI

Install Gemini CLI:

npm install -g @google/gemini-cli

Configure the server in %USERPROFILE%/.gemini/settings.json:
Navigate to %USERPROFILE%/.gemini in File Explorer and open settings.json.
Add the windows-mcp config in the settings.json and save it.

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

Note: To run from source, replace the command with uv and args with ["--directory", "<path>", "run", "windows-mcp"].

Rerun Gemini CLI in terminal. Enjoy 🥳

Install in Qwen Code

1. Install Qwen Code:

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

Configure the server in %USERPROFILE%/.qwen/settings.json:
Navigate to %USERPROFILE%/.qwen/settings.json.
Add the windows-mcp config in the settings.json and save it.

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

Note: To run from source, replace the command with uv and args with ["--directory", "<path>", "run", "windows-mcp"].

Rerun Qwen Code in terminal. Enjoy 🥳

Install in Codex CLI

1. Install Codex CLI:

npm install -g @openai/codex

Configure the server in %USERPROFILE%/.codex/config.toml:
Navigate to %USERPROFILE%/.codex/config.toml.
Add the windows-mcp config in the config.toml and save it.

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

Note: To run from source, replace the command with uv and args with ["--directory", "<path>", "run", "windows-mcp"].

Rerun Codex CLI in terminal. Enjoy 🥳

🖥️ Modes

Windows-MCP supports two operating modes: Local (default) and Remote.

Local Mode (Default)

In local mode, Windows-MCP runs directly on your Windows machine and exposes its tools to the connected MCP client. This is the standard setup for personal use.

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

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

No additional environment variables are needed. The MCP client connects directly to the server.

Remote Mode

In remote mode, Windows-MCP acts as a proxy that connects to the windowsmcp.io enabling cloud-hosted Windows automation. This is designed for scenarios where the MCP client is remote and connects through the dashboard, which routes requests to a Windows VM running Windows-MCP.

Required environment variables:

Variable	Description
`MODE`	Set to `remote`
`SANDBOX_ID`	The sandbox/VM identifier from the dashboard
`API_KEY`	Your Windows-MCP API key

Example configuration:

{
  "mcpServers": {
    "windows-mcp": {
      "command": "uvx",
      "args": [
        "windows-mcp"
      ],
      "env": {
        "MODE": "remote",
        "SANDBOX_ID": "your-sandbox-id",
        "API_KEY": "your-api-key"
      }
    }
  }
}

Transport Options

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

🔨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.
Snapshot: Combined snapshot of default language, browser, active apps and interactive, textual and scrollable elements along with screenshot of the desktop. Supports use_dom=True for browser content extraction (web page elements only), use_vision=True for including screenshots, and use_ocr=True for extracting visible text via Tesseract OCR (requires winget install UB-Mannheim.TesseractOCR).
App: To launch an application from the start menu, resize or move the window and switch between apps.
Shell: To execute PowerShell commands.
Scrape: To scrape the entire webpage for information.
MultiSelect: Select multiple items (files, folders, checkboxes) with optional Ctrl key.
MultiEdit: Enter text into multiple input fields at specified coordinates.
Clipboard: Read or set Windows clipboard content.
Process: List running processes or terminate them by PID or name.
SystemInfo: Get system information including CPU, memory, disk, network stats, and uptime.
Notification: Send a Windows toast notification with a title and message.
LockScreen: Lock the Windows workstation.
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, add the following to your MCP client configuration:

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

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.

📝 Limitations

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

🪪 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

@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}
}

Name		Name	Last commit message	Last commit date
Latest commit History 232 Commits
.github		.github
assets		assets
src/windows_mcp		src/windows_mcp
tests		tests
.gitignore		.gitignore
.mcpbignore		.mcpbignore
.python-version		.python-version
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE.md		LICENSE.md
README.md		README.md
SECURITY.md		SECURITY.md
manifest.json		manifest.json
pyproject.toml		pyproject.toml
server.json		server.json
uv.lock		uv.lock

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

🪟 Windows-MCP

Updates

Supported Operating Systems

🎥 Demos

✨ Key Features

🛠️Installation

Prerequisites

🖥️ Modes

Local Mode (Default)

Remote Mode

Transport Options

🔨MCP Tools

🤝 Connect with Us

Star History

👥 Contributors

🔒 Security

📊 Telemetry

📝 Limitations

🪪 License

🙏 Acknowledgements

🤝Contributing

Citation

About

Uh oh!

Releases 7

Sponsor this project

Uh oh!

Packages

Uh oh!

Contributors 16

Languages

Uh oh!

License

CursorTouch/Windows-MCP

Folders and files

Latest commit

History

Repository files navigation

🪟 Windows-MCP

Updates

Supported Operating Systems

🎥 Demos

✨ Key Features

🛠️Installation

Prerequisites

🖥️ Modes

Local Mode (Default)

Remote Mode

Transport Options

🔨MCP Tools

🤝 Connect with Us

Star History

👥 Contributors

🔒 Security

📊 Telemetry

📝 Limitations

🪪 License

🙏 Acknowledgements

🤝Contributing

Citation

About

Topics

Resources

License

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 7

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Contributors 16

Languages

Packages