
windows-mcp
Connect an existing Windows-MCP instance (RDP + Windows MCP) to the Strawberry terminal sidebar and tasks
- version
- 0.1.0
Install
/plugin install windows-mcp@strawberry-pluginsRun it inside Claude Code after adding the marketplace with /plugin marketplace add LiamFuller07/strawberry-terminal-plugin.
Contents
Discovered from sourceAgents 6
GCP Windows-MCP Setup Guide
This guide explains how to configure the Windows-MCP plugin to connect to Windows VMs in Google Cloud Platform.
Architecture Overview
┌─────────────────────┐ ┌──────────────────────┐ ┌─────────────────┐
│ Strawberry CLI │────▶│ Cloud Function │────▶│ Secret Manager │
│ (bootstrap.mjs) │ │ get-windows-creds │ │ VM credentials │
└─────────────────────┘ └──────────────────────┘ └─────────────────┘
│ │
│ ▼
│ ┌──────────────────────┐
│ │ Compute Engine │
│ │ VM Pool (Windows) │
│ └──────────────────────┘
│ │
▼ ▼
┌─────────────────────┐ ┌──────────────────────┐
│ tunnel-manager.js │◀────│ IAP TCP Tunnel │
│ (localhost:7788) │ │ or SSH Tunnel │
└─────────────────────┘ └──────────────────────┘
│
▼
┌─────────────────────┐
│ Windows-MCP │
│ (State/Click/Type) │
└─────────────────────┘
Prerequisites
- Google Cloud Project with billing enabled
- gcloud CLI installed and authenticated
- Windows VM with Windows-MCP running (uvx windows-mcp)
- IAP API enabled (for IAP tunneling)
Quick Start
1. Deploy the Cloud Function
cd plugins/windows-mcp/cloud-function
# Install dependencies
npm install
# Deploy to GCP
gcloud functions deploy get-windows-credentials \
--gen2 \
--runtime=nodejs20 \
--region=us-central1 \
--source=. \
--entry-point=getWindowsCredentials \
--trigger-http \
--no-allow-unauthenticated \
--set-env-vars="GCP_PROJECT_ID=your-project-id,GCP_ZONE=us-central1-a"
2. Store Credentials in Secret Manager
# Create a secret with VM credentials
echo '{
"host": "10.128.0.2",
"username": "strawberry",
"password": "your-secure-password",
"port": 3389,
"mcp_port": 8080
}' | gcloud secrets create windows-mcp-credentials \
--data-file=- \
--project=your-project-id
3. Configure Environment Variables
Set these environment variables before running Strawberry:
# Required for GCP vault integration
export WINDOWS_MCP_VAULT_URL="https://us-central1-your-project.cloudfunctions.net/get-windows-credentials"
export GCP_PROJECT_ID="your-project-id"
export GCP_ZONE="us-central1-a"
# Optional
export TUNNEL_TYPE="iap" # or "ssh", "direct", "auto"
export WINDOWS_MCP_VM_NAME="windows-vm-1" # specific VM to use
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"
4. Run Strawberry
The plugin will automatically:
- Fetch credentials from the Cloud Function
- Create an IAP tunnel to the Windows VM
- Connect to Windows-MCP at localhost:7788
Configuration Options
Environment Variables
| Variable | Description | Default |
|---|---|---|
WINDOWS_MCP_VAULT_URL | Cloud Function URL for credentials | - |
GCP_PROJECT_ID | Google Cloud project ID | - |
GCP_ZONE | VM zone | us-central1-a |
TUNNEL_TYPE | Tunnel type: auto/iap/ssh/direct | auto |
WINDOWS_MCP_VM_NAME | Specific VM name to use | - |
WINDOWS_MCP_ENDPOINT | Direct endpoint (bypasses vault) | - |
GOOGLE_APPLICATION_CREDENTIALS | Service account key file | ADC |
Tunnel Types
- auto: Automatically detect best tunnel (IAP if zone/vm_name, SSH if host)
- iap: Use IAP TCP tunneling (recommended for GCP VMs)
- ssh: Use SSH port forwarding
- direct: No tunnel, connect directly to host:port
- cloudflare: Use Cloudflare Tunnel
Windows VM Setup
1. Create Windows VM
gcloud compute instances create windows-mcp-vm \
--project=your-project-id \
--zone=us-central1-a \
--machine-type=n1-standard-2 \
--image-family=windows-2022 \
--image-project=windows-cloud \
--boot-disk-size=50GB \
--labels=purpose=windows-mcp \
--metadata=enable-osconfig=TRUE
2. Install Windows-MCP on VM
RDP into the VM and run:
# Install Python and uv
winget install Python.Python.3.12
pip install uv
# Run Windows-MCP
uvx windows-mcp --port 8080
3. Configure Firewall Rules
For IAP tunneling, no external firewall rules needed. For direct access:
gcloud compute firewall-rules create allow-windows-mcp \
--project=your-project-id \
--direction=INGRESS \
--priority=1000 \
--network=default \
--action=ALLOW \
--rules=tcp:8080 \
--source-ranges=35.235.240.0/20 \
--target-tags=windows-mcp
VM Pool Management
The Cloud Function supports a VM pool for multi-user scenarios:
- Label VMs: Add
purpose=windows-mcplabel to pool VMs - Automatic Assignment: Function assigns available VMs to sessions
- Session Tracking: VMs are marked in-use via metadata
- Auto Release: Sessions expire after 2 hours
Scaling the Pool
# Create multiple VMs
for i in {1..3}; do
gcloud compute instances create windows-mcp-vm-$i \
--project=your-project-id \
--zone=us-central1-a \
--machine-type=n1-standard-2 \
--image-family=windows-2022 \
--image-project=windows-cloud \
--labels=purpose=windows-mcp
done
Troubleshooting
"Failed to obtain Google Cloud access token"
- Run
gcloud auth loginto authenticate - Or set
GOOGLE_APPLICATION_CREDENTIALSto a service account key
"IAP tunnel timeout"
- Ensure IAP API is enabled:
gcloud services enable iap.googleapis.com - Check IAP permissions:
roles/iap.tunnelResourceAccessor - Verify VM is running:
gcloud compute instances list
"VM pool exhausted"
- Add more VMs to the pool
- Check for stuck sessions in VM metadata
- Manually release VMs via the Cloud Function
Checking Tunnel Status
node bin/tunnel-manager.js status
Manual Vault Sync
WINDOWS_MCP_VAULT_URL="https://..." node bin/vault-sync.js
Security Best Practices
- Use IAP tunneling instead of exposing VMs publicly
- Rotate credentials regularly via Secret Manager
- Use service accounts instead of user credentials
- Enable audit logging for Cloud Functions
- Restrict IAP access to specific users/groups
File Structure
plugins/windows-mcp/
├── .mcp.json # MCP server configuration
├── GCP_SETUP.md # This guide
├── bin/
│ ├── vault-sync.js # GCP credential fetcher
│ ├── tunnel-manager.js # IAP/SSH tunnel manager
│ └── start-windows-mcp.js # RDP launcher helper
├── cloud-function/
│ ├── index.js # Cloud Function code
│ └── package.json # Function dependencies
├── servers/windows-mcp/
│ └── bootstrap.mjs # Main bootstrap orchestrator
└── windows-mcp/ # Bundled Windows-MCP Python package
Windows-MCP plugin for Strawberry Terminal
This plugin exposes the CursorTouch Windows-MCP MCP server inside the Strawberry terminal marketplace. Use it when you want to control existing Windows RDP machines instead of spawning new TryCua VMs.
How it works
- Place your Windows-MCP repo in
plugins/windows-mcp/windows-mcp(already included). - On the Windows host (the RDP target) install
uvand runuv run windows-mcp. Make sure the MCP server is reachable over TCP/HTTP. - Point Strawberry to the running endpoint by setting
WINDOWS_MCP_ENDPOINT(e.g.http://192.168.1.7:8080). - The plugin can fall back to launching the bundled Windows-MCP locally (macOS/Linux) by running
uv --directory <path> run windows-mcp, but for real Windows automation you should tunnel your RDP host to that endpoint.
Auto-launch helper
- The helper
bin/start-windows-mcp.jsparses your.rdpfile (/Users/liam/Downloads/savelli-marketing-job.rdp), startsxfreerdp, and runsuvx windows-mcpon the Windows desktop so you never have to manually log in and start the server. - On macOS install FreeRDP (
brew install freerdp) soxfreerdpis available. - Environment overrides:
WINDOWS_MCP_AUTO_LAUNCH– set tofalseto skip the helper (defaults totrue).WINDOWS_MCP_REMOTE_DIR– directory on Windows containing the Windows-MCP repo (C:\\WindowsMCPby default).WINDOWS_MCP_REMOTE_CMD– command executed on Windows to start the MCP server.WINDOWS_MCP_PASSWORD– password when the.rdpfile omits credentials.WINDOWS_MCP_PORT– port to target when RDP is running on a non-standard port.
RDP test file
Use /Users/liam/Downloads/savelli-marketing-job.rdp as the test target. Open it in Microsoft Remote Desktop, configure port forwarding so the Strawberry host can reach the MCP HTTP endpoint, and set WINDOWS_MCP_ENDPOINT accordingly.
Tips
- Keep the Windows-MCP terminal running while you automate (State → Click/Type → Scroll).
- Call
State-Toolwithuse_vision=trueto populate screenshots for the sidebar. - Map the
Click-Toolcoordinates from the State output before driving mouse actions.
Contributing to Windows-MCP
Thank you for your interest in contributing to Windows-MCP! We welcome contributions from the community to help make this project better. This document provides guidelines and instructions for contributing.
Table of Contents
- Code of Conduct
- Getting Started
- Development Workflow
- Testing
- Pull Requests
- Documentation
- Reporting Issues
- Security Vulnerabilities
- Getting Help
Code of Conduct
By participating in this project, you agree to maintain a respectful and inclusive environment. We expect all contributors to:
- Be respectful and considerate in communication
- Welcome newcomers and help them get started
- Accept constructive criticism gracefully
- Focus on what's best for the community and project
Getting Started
Prerequisites
Before you begin, ensure you have:
- Windows OS: Windows 7, 8, 8.1, 10, or 11
- Python 3.13+: Download Python
- UV Package Manager: Install with
pip install uvor see UV documentation - Git: Download Git
- A GitHub account: Sign up here
Development Environment Setup
-
Fork the Repository
Click the "Fork" button on the Windows-MCP repository to create your own copy.
-
Clone Your Fork
git clone https://github.com/YOUR_USERNAME/Windows-MCP.git cd Windows-MCP -
Add Upstream Remote
git remote add upstream https://github.com/CursorTouch/Windows-MCP.git -
Install Dependencies
uv sync -
Verify Installation
uv run main.py --help
Development Workflow
Branching Strategy
mainbranch contains the latest stable code- Create feature branches from
mainusing descriptive names:- Features:
feature/add-new-tool - Bug fixes:
fix/click-tool-coordinates - Documentation:
docs/update-readme - Refactoring:
refactor/desktop-service
- Features:
Making Changes
-
Create a New Branch
git checkout -b feature/your-feature-name -
Make Your Changes
- Write clean, readable code
- Follow the existing code structure
- Add comments for complex logic
- Update documentation as needed
-
Test Your Changes
- Test manually in a safe environment (VM recommended)
- Add automated tests if applicable
- Ensure existing functionality isn't broken
-
Commit Your Changes
git add . git commit -m "Add feature: description of your changes"
Commit Messages
While we don't enforce a strict commit message format, please make your commits informative:
Good examples:
Add support for multi-monitor setups in State-ToolFix Click-Tool coordinate offset on high DPI displaysUpdate README with Perplexity Desktop installation stepsRefactor Desktop class to improve error handling
Avoid:
fix bugupdatechanges
Code Style
We use Ruff for code formatting and linting.
Key Guidelines:
- Line length: 100 characters maximum
- Quotes: Use double quotes for strings
- Naming conventions: Follow PEP 8
snake_casefor functions and variablesPascalCasefor classesUPPER_CASEfor constants
- Type hints: Add type annotations to function signatures
- Docstrings: Use Google-style docstrings for all public functions and classes
Example:
def click_tool(
loc: list[int],
button: Literal['left', 'right', 'middle'] = 'left',
clicks: int = 1
) -> str:
"""Click on UI elements at specific coordinates.
Args:
loc: List of [x, y] coordinates to click
button: Mouse button to use (left, right, or middle)
clicks: Number of clicks (1=single, 2=double, 3=triple)
Returns:
Confirmation message describing the action performed
Raises:
ValueError: If loc doesn't contain exactly 2 integers
"""
if len(loc) != 2:
raise ValueError("Location must be a list of exactly 2 integers [x, y]")
# Implementation...
Format Code:
ruff format .
Run Linter:
ruff check .
Testing
Running Tests
If the project has tests (check the tests/ directory):
pytest
Run specific test files:
pytest tests/test_desktop.py
Run with coverage:
pytest --cov=src tests/
Adding Tests
When adding new features:
- Create test files in the
tests/directory matching the module structure - Write unit tests for individual functions
- Write integration tests for tool workflows
- Use fixtures for common test setup
- Mock external dependencies (Windows API calls, file system operations)
Example Test:
import pytest
from src.desktop.service import Desktop
def test_click_tool_validates_coordinates():
"""Test that click_tool raises ValueError for invalid coordinates."""
with pytest.raises(ValueError, match="exactly 2 integers"):
click_tool([100]) # Missing y coordinate
Pull Requests
Before Submitting
- Code follows the project's style guidelines
- All tests pass (if applicable)
- Documentation is updated (README, docstrings, etc.)
- Commit messages are clear and descriptive
- Changes are tested in a safe environment (VM recommended)
- No sensitive information (API keys, passwords) is included
Pull Request Process
-
Update Your Branch
git fetch upstream git rebase upstream/main -
Push to Your Fork
git push origin feature/your-feature-name -
Create Pull Request
- Go to the Windows-MCP repository
- Click "New Pull Request"
- Select your fork and branch
- Fill out the PR template with:
- Description: What does this PR do?
- Motivation: Why is this change needed?
- Testing: How was this tested?
- Screenshots: If applicable (UI changes, new features)
- Related Issues: Link any related issues
-
Respond to Feedback
- Address reviewer comments promptly
- Make requested changes in new commits
- Push updates to the same branch
Review Process
- Maintainers will review your PR within a few days
- You may be asked to make changes or provide clarification
- Once approved, a maintainer will merge your PR
- Your contribution will be acknowledged in release notes
Documentation
Good documentation is crucial! When contributing:
Code Documentation
- Docstrings: Add to all public functions, classes, and methods
- Comments: Explain complex logic or non-obvious decisions
- Type hints: Help users and tools understand your code
User Documentation
Update relevant documentation files:
- README.md: For user-facing features or installation changes
- SECURITY.md: For security-related changes
- CONTRIBUTING.md: For development process changes
Tool Documentation
When adding or modifying tools:
- Update the tool's
descriptionparameter inmain.py - Add appropriate
ToolAnnotations - Update the tools list in
README.md - Update
manifest.jsonif needed
Reporting Issues
Found a bug or have a feature request? Please open an issue!
Bug Reports
Include:
- Description: Clear description of the bug
- Steps to Reproduce: Detailed steps to recreate the issue
- Expected Behavior: What should happen
- Actual Behavior: What actually happens
- Environment: Windows version, Python version, MCP client
- Screenshots/Logs: If applicable
Feature Requests
Include:
- Description: What feature do you want?
- Use Case: Why is this feature needed?
- Proposed Solution: How might this be implemented?
- Alternatives: Other approaches you've considered
Security Vulnerabilities
DO NOT report security vulnerabilities through public GitHub issues.
Instead, please:
- Email the maintainers at jeogeoalukka@gmail.com
- Or use GitHub Security Advisories
See our Security Policy for more details.
Getting Help
Need help with your contribution?
- Discord: Join our Discord Community
- Twitter/X: Follow @CursorTouch
- GitHub Discussions: Ask questions in Discussions
- Issues: Open an issue for technical questions
Types of Contributions
We welcome many types of contributions:
Code Contributions
- New Tools: Add new MCP tools for Windows automation
- Bug Fixes: Fix issues in existing tools
- Performance Improvements: Optimize code for speed or efficiency
- Refactoring: Improve code structure and maintainability
Non-Code Contributions
- Documentation: Improve README, guides, or docstrings
- Testing: Add test cases or improve test coverage
- Bug Reports: Report issues with detailed information
- Feature Requests: Suggest new features or improvements
- Community Support: Help others in Discord or Discussions
- Translations: Help translate documentation (future)
Recognition
Contributors are recognized in:
- GitHub contributors page
- Release notes for significant contributions
- Special mentions for major features or fixes
License
By contributing to Windows-MCP, you agree that your contributions will be licensed under the MIT License.
Thank you for contributing to Windows-MCP! Your efforts help make this project better for everyone. 🙏
Made with ❤️ by the CursorTouch community
MIT License
Copyright (c) 2025 JEOMON GEORGE
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
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 1M+ Users in Claude Desktop Extensiosn.
- Windows-MCP is now available on PyPI (thus supports
uvx windows-mcp) - Windows-MCP is added to MCP Registry
- Try out 🪟Windows-Use!!, an agent built using Windows-MCP.
- Windows-MCP is now featured as Desktop Extension in
Claude Desktop.
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.7 to 2.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
Specialuse_dom=Truemode for State-Tool that focuses exclusively on web page content, filtering out browser UI elements for cleaner, more efficient web automation.
🛠️Installation
Prerequisites
- Python 3.13+
- UV (Package Manager) from Astra, install with
pip install uvorcurl -LsSf https://astral.sh/uv/install.sh | sh Englishas the default language in Windows highly preferred or disable theApp-Toolin the MCP Server for Windows with other languages.
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
Saveand 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%/.geminiin File Explorer and opensettings.json. -
Add the
windows-mcpconfig in thesettings.jsonand 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-mcpconfig in thesettings.jsonand 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-mcpconfig in theconfig.tomland 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 🥳
🔨MCP Tools
MCP Client can access the following tools to interact with Windows:
Click-Tool: Click on the screen at the given coordinates.Type-Tool: Type text on an element (optionally clears existing text).Scroll-Tool: Scroll vertically or horizontally on the window or specific regions.Drag-Tool: Drag from one point to another.Move-Tool: Move mouse pointer.Shortcut-Tool: Press keyboard shortcuts (Ctrl+c,Alt+Tab, etc).Wait-Tool: Pause for a defined duration.State-Tool: Combined snapshot of default language, browser, active apps and interactive, textual and scrollable elements along with screenshot of the desktop. Supportsuse_dom=Truefor browser content extraction (web page elements only) anduse_vision=Truefor including screenshots.App-Tool: To launch an application from the start menu, resize or move the window and switch between apps.Shell-Tool: To execute PowerShell commands.Scrape-Tool: To scrape the entire webpage for information.
🤝 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
⚠️Caution
This MCP interacts directly with your Windows operating system to perform actions. Use with caution and avoid deploying it in environments where such risks cannot be tolerated.
🔒 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-Toolis 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}
}
Security Policy
Overview
Windows-MCP provides powerful automation capabilities that interact directly with your Windows operating system. This document outlines security considerations, best practices, and our commitment to maintaining a secure project.
⚠️ CRITICAL WARNING
READ THIS BEFORE DEPLOYING WINDOWS-MCP
Direct Operating System Interaction
Windows-MCP is NOT a sandboxed or isolated tool. It interacts directly with your actual Windows operating system on behalf of the connected LLM agent. This means:
- Real System Actions: Every tool call executes real actions on your physical or virtual Windows machine
- No Safety Net: There is no intermediate layer, simulation, or preview mode
- User Permissions: The MCP server operates on behalf of the user running it
Irreversible and Destructive Changes
Many operations performed by Windows-MCP CANNOT BE UNDONE:
- File Deletions: Files deleted through PowerShell or UI interactions may be permanently lost
- Data Overwrites: Text typed with
clear=Truereplaces existing content without recovery options - System Modifications: PowerShell commands can modify registry, services, and system configurations
- Application Actions: Clicking "Delete", "Yes", or "Confirm" buttons has real consequences
- No Undo/Rollback: Unlike text editors or IDEs, most Windows operations don't have an undo feature
Where NOT to Deploy
DO NOT deploy Windows-MCP on systems where you cannot tolerate the risk of:
- ❌ Accidental data loss or corruption
- ❌ Unintended system configuration changes
- ❌ Exposure of sensitive information through screenshots
- ❌ Execution of malicious commands if the LLM is compromised
- ❌ Compliance violations in regulated environments
Specifically, NEVER deploy on:
- Production servers or workstations
- Systems containing irreplaceable data
- Machines with access to sensitive databases or networks
- Compliance-regulated environments (healthcare, finance, government)
- Shared systems or multi-user environments without explicit consent
- Any system you don't fully control and can't afford to lose
Recommended Safe Deployment
For safer experimentation and usage, strongly consider deploying Windows-MCP in:
✅ Virtual Machines (VMs)
- Use VMware, VirtualBox, Hyper-V, or similar virtualization platforms
- Take snapshots before each session for easy rollback
- Isolate the VM from production networks
- Limit VM access to non-sensitive resources only
✅ Sandboxed Environments
- Windows Sandbox (built into Windows 10/11 Pro/Enterprise)
- Containerized Windows environments
- Dedicated test machines with no production data
- Isolated network segments with restricted access
✅ Dedicated Test Systems
- Separate physical machines used only for testing
- Systems with regular backups and disaster recovery plans
- Machines that can be wiped and rebuilt without consequence
Impact Limitation Strategies
If you must use Windows-MCP on a regular system:
- Create a Dedicated User Account: Run the MCP server under a restricted user account with minimal permissions
- Regular Backups: Maintain frequent, verified backups of all important data
- Network Isolation: Disconnect from production networks or use firewall rules
- Supervised Operation: Always monitor the agent's actions in real-time
- Disable High-Risk Tools: Remove or restrict access to PowerShell-Tool and other destructive tools
- Test First: Thoroughly test workflows in a safe environment before production use
Security Considerations
System Access Level
Windows-MCP operates with the same permissions as the user running it. This means:
- Full System Access: The MCP server can perform any action that the current user can perform
- No Sandboxing: Tools execute directly on your Windows system without isolation
- Persistent Changes: Actions taken by the MCP server can permanently modify your system state
Tool-Specific Security Implications
Based on our tool annotations, here's the security profile of each tool:
High-Risk Tools (Potentially Destructive)
These tools can make permanent changes to your system:
| Tool | Risk | Description |
|---|---|---|
| Powershell-Tool | Critical | Can execute arbitrary PowerShell commands, including system modifications, file deletions, and network operations |
| Click-Tool | High | Can trigger destructive UI actions (delete confirmations, system dialogs) |
| Type-Tool | High | Can overwrite text, potentially destroying data when clear=True |
| Drag-Tool | High | Can move/reorganize files, potentially overwriting existing files |
| Shortcut-Tool | High | Can execute destructive keyboard shortcuts (Ctrl+D delete, Alt+F4 close) |
Medium-Risk Tools (Modifying but Non-Destructive)
These tools modify system state but are generally safe:
| Tool | Risk | Description |
|---|---|---|
| App-Tool | Medium | Launches/manages applications but doesn't modify data |
| Scroll-Tool | Low | Only changes viewport position |
| Move-Tool | Low | Only positions mouse cursor |
Low-Risk Tools (Read-Only)
These tools only read information without making changes:
| Tool | Risk | Description |
|---|---|---|
| State-Tool | Safe | Only captures desktop state and screenshots |
| Wait-Tool | Safe | Only pauses execution |
| Scrape-Tool | Safe* | Fetches web content (*may expose browsing activity) |
Best Practices
1. Run with Least Privilege
- Use a standard user account, not an administrator account, when possible
- Avoid running Windows-MCP with elevated privileges unless absolutely necessary
- Consider creating a dedicated user account for automation tasks
2. Trusted LLM Clients Only
- Only connect Windows-MCP to trusted MCP clients
- Be cautious when using with third-party or experimental LLM applications
- Review the client application's security practices before integration
3. Monitor Tool Usage
- Regularly review logs to understand what actions are being performed
- Be especially vigilant with high-risk tools (Powershell-Tool, Click-Tool, etc.)
- Set up alerts for unexpected or suspicious activity
4. Network Security
- When using SSE or HTTP transport modes, ensure proper network isolation
- Use localhost binding (
127.0.0.1) instead of0.0.0.0when possible - Implement firewall rules to restrict access to the MCP server ports
- Never expose the MCP server directly to the internet without proper authentication
5. Data Protection
- Be aware that State-Tool captures screenshots that may contain sensitive information
- Scrape-Tool may fetch content from untrusted websites
- Avoid using Windows-MCP in environments with highly sensitive data
- Consider disabling screenshot functionality (
use_vision=False) when handling confidential information
6. Code Review
- Review the source code before deployment in production environments
- Audit any custom extensions or modifications
- Keep dependencies up to date to patch known vulnerabilities
7. Backup and Recovery
- Maintain regular backups before using automation tools
- Test automation workflows in a safe environment first
- Have a recovery plan in case of unintended system changes
Deployment Recommendations
Recommended Use Cases
- Personal productivity automation on your own machine
- Development and testing environments
- QA automation in isolated test systems
- Controlled demonstrations with supervision
Use with Caution
- Shared workstations or multi-user systems
- Systems with access to production data
- Environments with compliance requirements (HIPAA, PCI-DSS, etc.)
- Automated workflows without human oversight
Not Recommended
- Production servers or critical infrastructure
- Systems handling highly sensitive data (financial, medical, personal)
- Public-facing systems or kiosks
- Environments where destructive actions cannot be tolerated
- Systems without proper backups
Vulnerability Reporting
We take security vulnerabilities seriously. If you discover a security issue, please follow responsible disclosure practices:
How to Report
DO NOT open a public GitHub issue for security vulnerabilities.
Instead, please report security issues via:
- Email: Send details to the project maintainers at jeogeoalukka@gmail.com
- GitHub Security Advisories: Use the GitHub Security Advisory feature (preferred)
What to Include
Please provide:
- Description of the vulnerability
- Steps to reproduce the issue
- Potential impact assessment
- Suggested fix (if available)
- Your contact information for follow-up
Response Timeline
- Initial Response: Within 48 hours
- Status Update: Within 7 days
- Fix Timeline: Depends on severity (critical issues prioritized)
We will acknowledge your contribution in the security advisory and release notes (unless you prefer to remain anonymous).
Security Updates
Staying Informed
- Watch this repository for security announcements
- Follow @CursorTouch on X for updates
- Join our Discord Community for discussions
Update Policy
- Security patches will be released as soon as possible
- Critical vulnerabilities will be addressed within 7 days
- Users will be notified via GitHub releases and community channels
Dependency Security
Windows-MCP relies on several third-party libraries. We:
- Regularly update dependencies to patch known vulnerabilities
- Monitor security advisories for our dependencies
- Use
uvfor reproducible dependency management
Key Dependencies
- PyAutoGUI: Mouse and keyboard automation
- UIAutomation: Windows UI interaction
- FastMCP: MCP server framework
- httpx: HTTP client for web scraping
Compliance and Auditing
Logging
Windows-MCP does not implement comprehensive audit logging by default. For compliance-sensitive environments, consider:
- Implementing custom logging middleware
- Using Windows Event Logging for system-level auditing
- Monitoring file system and registry changes
Telemetry and Data Privacy
- Windows-MCP collects anonymous usage data to help improve the MCP server.
- We collect:
- Tool execution status (success/failure)
- Execution duration
- Tool name
- Client name and version (e.g., Claude Desktop, etc.)
- Anonymized session IDs
- We DO NOT collect:
- Tool arguments (text typed, coordinates, file paths, etc.)
- Tool outputs (screenshots, commands results, page content, etc.)
- Personal Information (IP addresses are not stored, no user identifiers beyond a random UUID)
- Telemetry is enabled by default but can be disabled by setting the
ANONYMIZED_TELEMETRYenvironment variable tofalsein the MCP server configuration. - Windows-MCP processes commands locally on your machine.
- Screenshots and state captures remain on your local system.
- Web scraping may expose browsing activity to target websites.
Tool Annotations Reference
All tools include security-relevant annotations:
- readOnlyHint:
trueif the tool only reads data - destructiveHint:
trueif the tool may perform destructive updates - idempotentHint:
trueif repeated calls have no additional effect - openWorldHint:
trueif the tool interacts with external entities
Refer to main.py for complete tool annotations.
Disclaimer
USE AT YOUR OWN RISK
Windows-MCP is provided "as is" without warranty of any kind. The maintainers are not responsible for:
- Data loss or system damage caused by tool usage
- Security breaches resulting from improper configuration
- Actions performed by LLM agents using this MCP server
- Compliance violations in regulated environments
Users are solely responsible for:
- Ensuring appropriate use in their environment
- Implementing necessary security controls
- Complying with applicable laws and regulations
- Monitoring and auditing tool usage
License
This security policy is part of the Windows-MCP project, licensed under the MIT License. See LICENSE for details.
MCP servers 1
Sponsors
Details
- Marketplace
- LiamFuller07/strawberry-terminal-plugin
- Source
- plugins/windows-mcp
- Author
- CursorTouch
- Category
- Automation
- Keywords
- windows, mcp, rdp, automation, computer-use
