Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/dddabtc/winremote-mcp

Windows Remote MCP Server — 40+ tools for desktop automation, process management, file operations via FastMCP
https://github.com/dddabtc/winremote-mcp

agent automation claude mcp model-context-protocol openai openclaw python remote tooling windows

Last synced: about 2 months ago
JSON representation

Windows Remote MCP Server — 40+ tools for desktop automation, process management, file operations via FastMCP

Awesome Lists containing this project

README 

          
# WinRemote MCP — Run MCP Servers Remotely on Windows



[![PyPI version](https://img.shields.io/pypi/v/winremote-mcp)](https://pypi.org/project/winremote-mcp/)

[![Python](https://img.shields.io/pypi/pyversions/winremote-mcp)](https://pypi.org/project/winremote-mcp/)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[![CI](https://github.com/dddabtc/winremote-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/dddabtc/winremote-mcp/actions/workflows/ci.yml)

[![Downloads](https://static.pepy.tech/badge/winremote-mcp)](https://pepy.tech/projects/winremote-mcp)

[![win-remote-mcp MCP server](https://glama.ai/mcp/servers/dddabtc/win-remote-mcp/badges/score.svg)](https://glama.ai/mcp/servers/dddabtc/win-remote-mcp)



**The ultimate Windows MCP server for remote desktop control and automation.** Control any Windows machine through the Model Context Protocol — perfect for AI agents, Claude Desktop. Transform your Windows desktop into a powerful, remotely-accessible automation endpoint.



Run **on the Windows machine** you want to control. Built with [FastMCP](https://github.com/jlowin/fastmcp) and the [Model Context Protocol](https://modelcontextprotocol.io/).



## Quickstart (30 seconds)



```bash

# Install from PyPI

pip install winremote-mcp



# Start the Windows MCP server

winremote-mcp

```



That's it! Your Windows MCP server is now running on `http://127.0.0.1:8090` and ready to accept commands from MCP clients like Claude Desktop.



## 🤖 Agent Integrations



winremote-mcp works with MCP-compatible AI agents and clients. Client-specific setup guides live in this repo:



- [Hermes](skill/hermes/) — add winremote as a native streamable HTTP or stdio MCP server.

- [OpenClaw](skill/openclaw/) — use winremote as OpenClaw's Windows control layer.

- [Claude Desktop / Claude Code](skill/claude/) — configure local stdio or remote streamable HTTP.

- [Cursor](skill/cursor/) — add winremote to `.cursor/mcp.json`.



### Hermes Setup



Run winremote-mcp on the Windows machine, then add it to Hermes as an MCP server:



```powershell

pip install winremote-mcp

winremote-mcp --host 0.0.0.0 --port 8090 --auth-key "your-secret-key"

```



```yaml

mcp_servers:

  winremote:

    type: streamable-http

    url: http://:8090/mcp

    headers:

      Authorization: Bearer your-secret-key

```



See the full [Hermes integration guide](skill/hermes/) for local stdio setup, verification prompts, and available capabilities.



## 🤖 OpenClaw Integration



winremote-mcp is the official Windows control layer for [OpenClaw](https://github.com/openclaw/openclaw). Together they give your AI agent full remote control over any Windows machine — screenshots, PowerShell, file transfer, GUI automation, and more.



---



### The Easiest Way: Just Tell OpenClaw



You don't need to configure anything manually. Just tell your OpenClaw agent:



> "Install winremote-mcp on my Windows machine at `192.168.1.100` and connect it to yourself. Python is installed at `C:\Python311\python.exe`."



OpenClaw will SSH into the Windows machine, install the package, start the server, and wire up the MCP connection — all automatically.



---



### Manual Setup (Step by Step)



#### Step 1 — Install on Windows



```cmd

pip install winremote-mcp

```



#### Step 2 — Start the server



**Local-only quick start (default, safest):**

```cmd

winremote-mcp

```



**Remote access requires authentication:**



Starting with v0.4.20, `winremote-mcp` refuses to bind HTTP transport to a non-loopback address without authentication. Use an API key for LAN or remote access:



```cmd

winremote-mcp --host 0.0.0.0 --port 8090 --auth-key YOUR_SECRET_KEY

```



For lab-only legacy behavior, you can explicitly acknowledge the risk with `--allow-insecure-remote`; do not use this on shared, routed, or internet-exposed networks.



**Auto-start on boot:**

```cmd

winremote-mcp install

```



#### Step 3 — Connect OpenClaw



Add to your `openclaw.json`:



```json

{

  "plugins": {

    "entries": {

      "winremote": {

        "type": "mcp",

        "url": "http://192.168.1.100:8090/mcp",

        "headers": {

          "Authorization": "Bearer YOUR_SECRET_KEY"

        }

      }

    }

  }

}

```



Or tell your OpenClaw agent:

> "Add winremote MCP at `http://192.168.1.100:8090/mcp` with auth key `YOUR_SECRET_KEY`."



#### Step 4 — What your agent can do



Once connected, your AI agent has full Windows control:



| Capability | Example |

|------------|---------|

| 🖥️ Screenshots | Capture the full desktop or a specific window |

| ⚡ Shell execution | Run PowerShell, CMD, or batch scripts |

| 📁 File transfer | Upload/download files between Linux and Windows |

| 🖱️ GUI automation | Click, type, drag — control any Windows app |

| 🔧 System info | Process list, services, event logs, registry |

| 📷 OCR | Extract text from any screen region |

| 🎬 Screen recording | Record desktop activity as GIF |



---



### Secure Remote Access (HTTPS)



For access over the internet or untrusted networks, enable HTTPS:



**Step 1 — Generate a certificate:**

```bash

# Self-signed (LAN/homelab)

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes



# Trusted cert (no browser warnings) — requires mkcert installed

mkcert -install && mkcert 192.168.1.100

```



**Step 2 — Start with TLS:**

```cmd

winremote-mcp --host 0.0.0.0 --port 8090 ^

  --auth-key YOUR_SECRET_KEY ^

  --ssl-certfile cert.pem ^

  --ssl-keyfile key.pem

```



**OpenClaw config with HTTPS:**

```json

{

  "plugins": {

    "entries": {

      "winremote": {

        "type": "mcp",

        "url": "https://192.168.1.100:8090/mcp",

        "headers": {

          "Authorization": "Bearer YOUR_SECRET_KEY"

        }

      }

    }

  }

}

```



---



### OAuth 2.0 (for Claude Desktop and other MCP clients)



Some MCP clients (like Claude Desktop) use OAuth instead of API keys. OAuth is a pre-provisioned confidential-client flow: configure both client ID and client secret on the server, then copy the same values into the client. Dynamic client registration is disabled, and redirect URIs must be loopback `http(s)` URIs.



```cmd

winremote-mcp --host 0.0.0.0 --port 8090 ^

  --ssl-certfile cert.pem --ssl-keyfile key.pem ^

  --oauth-client-id my-client --oauth-client-secret my-secret

```



**Claude Desktop config (`claude_desktop_config.json`):**

```json

{

  "mcpServers": {

    "winremote": {

      "type": "http",

      "url": "https://192.168.1.100:8090/mcp/",

      "oauth": {

        "clientId": "my-client",

        "clientSecret": "my-secret"

      }

    }

  }

}

```



---



### `winremote.toml` — Full Config Reference



Place in your working directory or `~/.config/winremote/winremote.toml`:



```toml

[server]

host         = "0.0.0.0"

port         = 8090

auth_key     = "your-secret-key"

# Optional break-glass flag for legacy trusted-LAN deployments only.

# Remote HTTP without auth is refused unless this is true.

allow_insecure_remote = false

ssl_certfile = "C:/certs/cert.pem"   # optional — enables HTTPS

ssl_keyfile  = "C:/certs/key.pem"    # optional — enables HTTPS



[security]

ip_allowlist        = ["192.168.1.0/24"]   # restrict to LAN only

oauth_client_id     = ""                    # optional OAuth client ID

oauth_client_secret = ""                    # optional OAuth secret



[tools]

exclude = ["ScreenRecord"]   # disable specific tools

```



---



> **Note:** winremote-mcp is a standard MCP server and works with any MCP-compatible client — Claude Desktop, Cursor, OpenClaw, and others.



## What's New in v0.4.21



### 📚 README release notes cleanup



- README now keeps only the latest three `What's New` sections.

- Older release notes now point to the full [CHANGELOG](CHANGELOG.md) to keep the README focused.



## What's New in v0.4.20



### 🔒 Security hardening



- Remote HTTP access now requires authentication by default. Non-loopback binds are refused unless you configure `--auth-key` or OAuth confidential-client auth.

- `--allow-insecure-remote` is still available, but only as an explicit legacy / lab-only break-glass option.

- OAuth dynamic client registration is disabled. OAuth now requires a pre-provisioned confidential client with client ID and client secret.

- OAuth now requires PKCE `S256` and loopback redirect URIs.

- `Scrape` and `PlaySound` URL fetching now blocks private, loopback, link-local, multicast, reserved, and unspecified targets to reduce SSRF risk.

- `App` and `PlaySound` moved to Tier 3 because they can start programs or trigger server-side effects.



### 🛡️ CI and supply-chain checks



- Added CI security scans with Bandit, pip-audit, and zizmor.

- Raised minimum dependency versions for FastMCP, Pillow, Authlib, cryptography, python-multipart, pytest, and Pygments.

- Tightened GitHub Actions permissions and pinned workflow actions to immutable SHAs.



## What's New in v0.4.19



### 🤖 Hermes Integration



- Added a Hermes setup guide for connecting winremote-mcp as a native MCP server.

- Added README links to client-specific integration guides in this repository.



For older release notes, see the full [CHANGELOG](CHANGELOG.md).



## What Problem It Solves



- **Remote Windows Control**: Control Windows desktops from anywhere through standardized MCP protocol

- **AI Agent Integration**: Enable Claude, GPT, and other AI agents to interact with Windows GUI applications  

- **Cross-Platform Automation**: Bridge the gap between Linux/macOS development environments and Windows targets

- **Headless Windows Management**: Manage Windows servers and workstations without RDP or VNC overhead



## Features



- **Desktop Control** — Screenshot capture (JPEG compressed, multi-monitor), click, type, scroll, keyboard shortcuts

- **Window Management** — Focus windows, minimize-all, launch/resize applications, multi-monitor support

- **Remote Shell Access** — PowerShell command execution with working directory support

- **File Operations** — Read, write, list, search files; binary transfer via base64 encoding

- **System Administration** — Windows Registry access, service management, scheduled tasks, process control

- **Network Tools** — Ping hosts, check TCP ports, monitor network connections

- **Advanced Features** — OCR text extraction, screen recording (GIF), annotated screenshots with UI element labels

- **AI Vision Support** — Works with Flutter, Electron, Qt and any UI via AI vision. See [Vision Guide](docs/vision-guide.md)

- **Security & Auth** — Optional API key authentication, localhost-only binding by default



## Installation



### From PyPI (Recommended)

```bash

pip install winremote-mcp

```



### From Source

```bash

git clone https://github.com/dddabtc/winremote-mcp.git

cd winremote-mcp

pip install .

```



### With Optional Dependencies

```bash

# Install with OCR support (includes pytesseract)

pip install winremote-mcp[ocr]



# Install development dependencies

pip install winremote-mcp[test]

```



### OCR Setup (Optional)

For text extraction from screenshots:

```bash

# 1. Install Tesseract OCR engine

winget install UB-Mannheim.TesseractOCR



# 2. Install with OCR dependencies

pip install winremote-mcp[ocr]

```



## Usage



### Basic Usage



### Tier and tool controls

```bash

# Default: tier1 + tier2 enabled, tier3 disabled

winremote-mcp



# Enable destructive tier3 tools

winremote-mcp --enable-tier3



# Disable interactive tier2 (tier1 only)

winremote-mcp --disable-tier2



# Both together: tier1 + tier3 (tier2 disabled)

winremote-mcp --enable-tier3 --disable-tier2



# Backward-compatible: enable everything

winremote-mcp --enable-all



# Explicit tool list (highest precedence over tier flags)

winremote-mcp --tools Snapshot,Click,Type



# Remove specific tools from resolved set

winremote-mcp --enable-tier3 --exclude-tools Shell,FileWrite

```



### Config file (`winremote.toml`)

Search order:

1. `--config /path/to/winremote.toml`

2. `./winremote.toml`

3. `~/.config/winremote/winremote.toml`



```toml

[server]

host = "127.0.0.1"

port = 8090

auth_key = ""

ssl_certfile = ""       # Path to SSL certificate for HTTPS

ssl_keyfile = ""        # Path to SSL private key for HTTPS



[security]

ip_allowlist = ["127.0.0.1", "192.168.1.0/24"]

enable_tier3 = false

disable_tier2 = false

oauth_client_id = ""    # Expected OAuth client ID (optional)

oauth_client_secret = "" # OAuth client secret for confidential clients



[tools]

enable = ["Snapshot", "Click", "Type"]

exclude = []

```



**Precedence:** CLI flags override config file values; config file values override defaults.



### IP allowlist

```bash

# CLI

winremote-mcp --ip-allowlist 127.0.0.1,192.168.1.0/24



# Or via config [security].ip_allowlist

```



Supports both single IPs and CIDR ranges (IPv4/IPv6). Non-allowlisted clients receive HTTP 403 with a clear error.



### HTTPS / TLS



To enable HTTPS, provide SSL certificate and key files:



```bash

winremote-mcp --ssl-certfile cert.pem --ssl-keyfile key.pem

```



Or in `winremote.toml`:

```toml

[server]

ssl_certfile = "/path/to/cert.pem"

ssl_keyfile  = "/path/to/key.pem"

```



**Generate a self-signed certificate** (for local/LAN use):

```bash

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

```



### OAuth 2.0



WinRemote MCP includes a built-in OAuth 2.0 Authorization Server, compatible with Claude Desktop and other MCP clients that require OAuth.



Enable it with:

```bash

winremote-mcp --oauth-client-id my-client --oauth-client-secret my-secret

```



Or in `winremote.toml`:

```toml

[security]

oauth_client_id     = "my-client"

oauth_client_secret = "my-secret"

```



**Claude Desktop config** (`claude_desktop_config.json`):

```json

{

  "mcpServers": {

    "winremote": {

      "type": "http",

      "url": "https://your-host:8080/mcp/",

      "oauth": {

        "clientId": "my-client",

        "clientSecret": "my-secret"

      }

    }

  }

}

```



The OAuth server implements:

- `GET /.well-known/oauth-authorization-server` — server metadata (RFC 8414)

- `POST /oauth/register` — dynamic client registration (RFC 7591)

- `GET /oauth/authorize` — Authorization Code + PKCE (RFC 7636)

- `POST /oauth/token` — token exchange



### Health check

```bash

# Start MCP server (localhost only, no auth)

winremote-mcp



# Start with remote access and authentication

winremote-mcp --host 0.0.0.0 --port 8090 --auth-key "your-secret-key"



# Enable all tools including high-risk Tier 3 (Shell, FileWrite, etc.)

winremote-mcp --enable-all



# Start with hot reload for development

winremote-mcp --reload

```



### MCP Client Configuration



**For Claude Desktop (`claude_desktop_config.json`):**

```json

{

  "mcpServers": {

    "winremote": {

      "command": "winremote-mcp",

      "args": ["--transport", "stdio"]

    }

  }

}

```



**For HTTP MCP clients:**

```json

{

  "mcpServers": {

    "winremote": {

      "type": "streamable-http", 

      "url": "http://192.168.1.100:8090/mcp",

      "headers": {

        "Authorization": "Bearer your-secret-key"

      }

    }

  }

}

```



### Auto-Start on Boot

```bash

# Create Windows scheduled task

winremote-mcp install



# Remove scheduled task  

winremote-mcp uninstall

```



## Security



Tools are organized into three risk tiers. By default, only Tier 1-2 tools are enabled.



| Tier | Risk | Default | Examples |

|------|------|---------|----------|

| **Tier 1** | Read-only | ✅ Enabled | Snapshot, GetSystemInfo, FileList |

| **Tier 2** | Interactive | ✅ Enabled | Click, Type, Shortcut, Scrape |

| **Tier 3** | Destructive / server-side effects | ❌ Disabled | Shell, App, PlaySound, FileWrite |



```bash

# Enable all tiers (use with caution)

winremote-mcp --enable-all



# Always use auth for remote access

winremote-mcp --host 0.0.0.0 --auth-key "your-secret-key"

```



See [SECURITY.md](SECURITY.md) for the full security guide.



## Tools



| Tool | Description |

|------|-------------|

| **Desktop** | |

| Snapshot | Screenshot (JPEG, configurable quality/max_width) + window list + UI elements |

| AnnotatedSnapshot | Screenshot with numbered labels on interactive elements |

| OCR | Extract text from screen via OCR (pytesseract or Windows built-in) |

| ScreenRecord | Record screen activity as animated GIF |

| PlaySound | Play audio file on Windows host (.wav/.mp3/.ogg/.wma/.m4a, local path or URL) |

| **Input** | |

| Click | Mouse click (left/right/middle, single/double/hover) |

| Type | Type text at coordinates |

| Scroll | Vertical/horizontal scroll |

| Move | Move mouse / drag |

| Shortcut | Keyboard shortcuts |

| Wait | Pause execution |

| **Window Management** | |

| FocusWindow | Bring window to front (fuzzy title match) |

| MinimizeAll | Show desktop (Win+D) |

| App | Launch/switch/resize applications |

| **System** | |

| Shell | Execute PowerShell commands (with optional cwd) |

| GetClipboard | Read clipboard |

| SetClipboard | Write clipboard |

| ListProcesses | Process list with CPU/memory |

| KillProcess | Kill process by PID or name |

| GetSystemInfo | System information |

| Notification | Windows toast notification |

| LockScreen | Lock workstation |

| ReconnectSession | Reconnect disconnected Windows desktop session to console |

| **File System** | |

| FileRead | Read file content |

| FileWrite | Write file content |

| FileList | List directory contents |

| FileSearch | Search files by pattern |

| FileDownload | Download file as base64 (binary) |

| FileUpload | Upload file from base64 (binary) |

| **Registry & Services** | |

| RegRead | Read Windows Registry value |

| RegWrite | Write Windows Registry value |

| ServiceList | List Windows services |

| ServiceStart | Start a Windows service |

| ServiceStop | Stop a Windows service |

| **Scheduled Tasks** | |

| TaskList | List scheduled tasks |

| TaskCreate | Create a scheduled task |

| TaskDelete | Delete a scheduled task |

| **Network** | |

| Scrape | Fetch URL content |

| Ping | Ping a host |

| PortCheck | Check if a TCP port is open |

| NetConnections | List network connections |

| EventLog | Read Windows Event Log entries |



## How It Works



```mermaid

graph LR

    A["MCP Client
(Claude/AI)"] -->|commands| B["WinRemote MCP
Server"]

    B -->|API calls| C["Windows APIs
(Win32/WMI/PS)"]

    C -->|results| B

    B -->|responses| A

```



**Transport Options:**

- **stdio**: Direct process communication (ideal for Claude Desktop)

- **HTTP**: RESTful API with optional authentication (ideal for remote access)



**Core Architecture:**

1. **Tool Layer**: 40+ Windows automation tools (screenshot, click, type, etc.)

2. **Task Manager**: Concurrency control and task cancellation

3. **Transport Layer**: MCP protocol over stdio or HTTP

4. **Security Layer**: Optional Bearer token authentication



## Working with Non-Standard UI Frameworks



`AnnotatedSnapshot` uses Win32 API to detect UI elements, which doesn't work with **Flutter, Electron, Qt**, or custom-drawn UIs. Three solutions:



| Approach | Setup | GPU | Best For |

|----------|-------|-----|----------|

| **Snapshot + Claude Vision** | None | No | Most users — Claude sees the screenshot and clicks |

| **[UI-TARS Desktop](https://github.com/bytedance/UI-TARS-desktop)** | Medium | 16 GB | Highest accuracy (94.2%), best Chinese UI support |

| **[OmniMCP](https://github.com/OpenAdaptAI/OmniMCP)** | Medium | 16 GB | Multi-LLM setups (LLM-agnostic) |



**Quick example** — no extra tools needed:

```

You:    "Take a screenshot with Snapshot, find the Connect button, and click it."

Claude:  1. Calls Snapshot() → sees the Flutter app screenshot

         2. Vision identifies "Connect" button at (520, 340)

         3. Calls Click(x=520, y=340)

```



For the complete guide with setup instructions, architecture diagrams, and comparison benchmarks, see **[docs/vision-guide.md](docs/vision-guide.md)**.



## Troubleshooting / FAQ



### Q: MCP server not starting?

**A:** Check Python version (requires 3.10+) and ensure no other service is using port 8090:

```bash

python --version

netstat -an | findstr :8090

```



### Q: Can't connect from remote machine?

**A:** Use `--host 0.0.0.0` to bind to all interfaces (default is localhost only):

```bash

winremote-mcp --host 0.0.0.0 --auth-key "secure-key"

```



### Q: Screenshot tool returns empty/black images?

**A:** Windows may be locked or display turned off. Ensure:

- Windows is unlocked and display is active

- No screen saver is running

- For multi-monitor setups, specify `monitor` parameter



### Q: OCR not working?

**A:** Install Tesseract OCR engine:

```bash

winget install UB-Mannheim.TesseractOCR

pip install winremote-mcp[ocr]

```



### Q: Permission errors with registry/services?

**A:** Run with administrator privileges:

```bash

# Right-click Command Prompt → "Run as administrator"

winremote-mcp

```



## Contributing



We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.



### Development Setup

```bash

git clone https://github.com/dddabtc/winremote-mcp.git

cd winremote-mcp

pip install -e ".[test]"

pytest  # Run tests

```



## Acknowledgments



Inspired by [Windows-MCP](https://github.com/CursorTouch/Windows-MCP) by CursorTouch. Thanks for the pioneering work on Windows desktop automation via MCP.



## License



This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.



---



**Ready to automate Windows with AI?** ⚡ Install `winremote-mcp` and connect your favorite AI agent to any Windows machine in under 30 seconds.