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-plugins

Run it inside Claude Code after adding the marketplace with /plugin marketplace add LiamFuller07/strawberry-terminal-plugin.

Contents

Discovered from source

Agents 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

  1. Google Cloud Project with billing enabled
  2. gcloud CLI installed and authenticated
  3. Windows VM with Windows-MCP running (uvx windows-mcp)
  4. 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:

  1. Fetch credentials from the Cloud Function
  2. Create an IAP tunnel to the Windows VM
  3. Connect to Windows-MCP at localhost:7788

Configuration Options

Environment Variables

VariableDescriptionDefault
WINDOWS_MCP_VAULT_URLCloud Function URL for credentials-
GCP_PROJECT_IDGoogle Cloud project ID-
GCP_ZONEVM zoneus-central1-a
TUNNEL_TYPETunnel type: auto/iap/ssh/directauto
WINDOWS_MCP_VM_NAMESpecific VM name to use-
WINDOWS_MCP_ENDPOINTDirect endpoint (bypasses vault)-
GOOGLE_APPLICATION_CREDENTIALSService account key fileADC

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:

  1. Label VMs: Add purpose=windows-mcp label to pool VMs
  2. Automatic Assignment: Function assigns available VMs to sessions
  3. Session Tracking: VMs are marked in-use via metadata
  4. 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"

  1. Run gcloud auth login to authenticate
  2. Or set GOOGLE_APPLICATION_CREDENTIALS to a service account key

"IAP tunnel timeout"

  1. Ensure IAP API is enabled: gcloud services enable iap.googleapis.com
  2. Check IAP permissions: roles/iap.tunnelResourceAccessor
  3. Verify VM is running: gcloud compute instances list

"VM pool exhausted"

  1. Add more VMs to the pool
  2. Check for stuck sessions in VM metadata
  3. 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

  1. Use IAP tunneling instead of exposing VMs publicly
  2. Rotate credentials regularly via Secret Manager
  3. Use service accounts instead of user credentials
  4. Enable audit logging for Cloud Functions
  5. 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

  1. Place your Windows-MCP repo in plugins/windows-mcp/windows-mcp (already included).
  2. On the Windows host (the RDP target) install uv and run uv run windows-mcp. Make sure the MCP server is reachable over TCP/HTTP.
  3. Point Strawberry to the running endpoint by setting WINDOWS_MCP_ENDPOINT (e.g. http://192.168.1.7:8080).
  4. 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.js parses your .rdp file (/Users/liam/Downloads/savelli-marketing-job.rdp), starts xfreerdp, and runs uvx windows-mcp on the Windows desktop so you never have to manually log in and start the server.
  • On macOS install FreeRDP (brew install freerdp) so xfreerdp is available.
  • Environment overrides:
    • WINDOWS_MCP_AUTO_LAUNCH – set to false to skip the helper (defaults to true).
    • WINDOWS_MCP_REMOTE_DIR – directory on Windows containing the Windows-MCP repo (C:\\WindowsMCP by default).
    • WINDOWS_MCP_REMOTE_CMD – command executed on Windows to start the MCP server.
    • WINDOWS_MCP_PASSWORD – password when the .rdp file 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-Tool with use_vision=true to populate screenshots for the sidebar.
  • Map the Click-Tool coordinates 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

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:

Development Environment Setup

  1. Fork the Repository

    Click the "Fork" button on the Windows-MCP repository to create your own copy.

  2. Clone Your Fork

    git clone https://github.com/YOUR_USERNAME/Windows-MCP.git
    cd Windows-MCP
    
  3. Add Upstream Remote

    git remote add upstream https://github.com/CursorTouch/Windows-MCP.git
    
  4. Install Dependencies

    uv sync
    
  5. Verify Installation

    uv run main.py --help
    

Development Workflow

Branching Strategy

  • main branch contains the latest stable code
  • Create feature branches from main using descriptive names:
    • Features: feature/add-new-tool
    • Bug fixes: fix/click-tool-coordinates
    • Documentation: docs/update-readme
    • Refactoring: refactor/desktop-service

Making Changes

  1. Create a New Branch

    git checkout -b feature/your-feature-name
    
  2. Make Your Changes

    • Write clean, readable code
    • Follow the existing code structure
    • Add comments for complex logic
    • Update documentation as needed
  3. Test Your Changes

    • Test manually in a safe environment (VM recommended)
    • Add automated tests if applicable
    • Ensure existing functionality isn't broken
  4. 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-Tool
  • Fix Click-Tool coordinate offset on high DPI displays
  • Update README with Perplexity Desktop installation steps
  • Refactor Desktop class to improve error handling

Avoid:

  • fix bug
  • update
  • changes

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_case for functions and variables
    • PascalCase for classes
    • UPPER_CASE for 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:

  1. Create test files in the tests/ directory matching the module structure
  2. Write unit tests for individual functions
  3. Write integration tests for tool workflows
  4. Use fixtures for common test setup
  5. 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

  1. Update Your Branch

    git fetch upstream
    git rebase upstream/main
    
  2. Push to Your Fork

    git push origin feature/your-feature-name
    
  3. 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
  4. 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:

  1. Update the tool's description parameter in main.py
  2. Add appropriate ToolAnnotations
  3. Update the tools list in README.md
  4. Update manifest.json if 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:

  1. Email the maintainers at jeogeoalukka@gmail.com
  2. Or use GitHub Security Advisories

See our Security Policy for more details.

Getting Help

Need help with your contribution?

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.

MseeP.ai Security Assessment Badge

🪟 Windows-MCP

License Python Platform: Windows 7 to 11 Last Commit
Follow on Twitter Join us on Discord

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

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 highly preferred or disable the App-Tool in the MCP Server for Windows with other languages.
Install in Claude Desktop
  1. Install Claude Desktop and
npm install -g @anthropic-ai/mcpb
  1. 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

  1. Clone the repository:
git clone https://github.com/CursorTouch/Windows-MCP.git
cd Windows-MCP
  1. Add this to your claude_desktop_config.json:
{
  "mcpServers": {
    "windows-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "<path to the windows-mcp directory>",
        "run",
        "windows-mcp"
      ]
    }
  }
}
  1. Open Claude Desktop and enjoy! 🥳

  2. 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
  1. Install Perplexity Desktop:

  2. Clone the repository.

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

cd Windows-MCP
  1. Open Perplexity Desktop:

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

  1. 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"
  ]
}
  1. 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
  1. Install Gemini CLI:
npm install -g @google/gemini-cli
  1. Configure the server in %USERPROFILE%/.gemini/settings.json:

  2. Navigate to %USERPROFILE%/.gemini in File Explorer and open settings.json.

  3. 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"].

  1. Rerun Gemini CLI in terminal. Enjoy 🥳
Install in Qwen Code 1. Install Qwen Code:
npm install -g @qwen-code/qwen-code@latest
  1. Configure the server in %USERPROFILE%/.qwen/settings.json:

  2. Navigate to %USERPROFILE%/.qwen/settings.json.

  3. 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"].

  1. Rerun Qwen Code in terminal. Enjoy 🥳
Install in Codex CLI 1. Install Codex CLI:
npm install -g @openai/codex
  1. Configure the server in %USERPROFILE%/.codex/config.toml:

  2. Navigate to %USERPROFILE%/.codex/config.toml.

  3. 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"].

  1. 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. Supports use_dom=True for browser content extraction (web page elements only) and use_vision=True for 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:

Star History

Star History Chart

⚠️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-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}
}

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=True replaces 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:

  1. Create a Dedicated User Account: Run the MCP server under a restricted user account with minimal permissions
  2. Regular Backups: Maintain frequent, verified backups of all important data
  3. Network Isolation: Disconnect from production networks or use firewall rules
  4. Supervised Operation: Always monitor the agent's actions in real-time
  5. Disable High-Risk Tools: Remove or restrict access to PowerShell-Tool and other destructive tools
  6. 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:

ToolRiskDescription
Powershell-ToolCriticalCan execute arbitrary PowerShell commands, including system modifications, file deletions, and network operations
Click-ToolHighCan trigger destructive UI actions (delete confirmations, system dialogs)
Type-ToolHighCan overwrite text, potentially destroying data when clear=True
Drag-ToolHighCan move/reorganize files, potentially overwriting existing files
Shortcut-ToolHighCan 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:

ToolRiskDescription
App-ToolMediumLaunches/manages applications but doesn't modify data
Scroll-ToolLowOnly changes viewport position
Move-ToolLowOnly positions mouse cursor
Low-Risk Tools (Read-Only)

These tools only read information without making changes:

ToolRiskDescription
State-ToolSafeOnly captures desktop state and screenshots
Wait-ToolSafeOnly pauses execution
Scrape-ToolSafe*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 of 0.0.0.0 when 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:

  1. Email: Send details to the project maintainers at jeogeoalukka@gmail.com
  2. 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

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 uv for 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_TELEMETRY environment variable to false in 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: true if the tool only reads data
  • destructiveHint: true if the tool may perform destructive updates
  • idempotentHint: true if repeated calls have no additional effect
  • openWorldHint: true if 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

More from LiamFuller07/strawberry-terminal-plugin

All 2