Winremote Mcp

WinRemote MCP — Run MCP Servers Remotely on Windows

[中文说明](README.zh-CN.md) | [English README](README.md)

[](https://pypi.org/project/winremote-mcp/) [](https://pypi.org/project/winremote-mcp/) [](https://opensource.org/licenses/MIT) [](https://github.com/dddabtc/winremote-mcp/actions/workflows/ci.yml) [](https://pepy.tech/projects/winremote-mcp) [](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 and the Model Context Protocol.

Quickstart (30 seconds)

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

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

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

pip install winremote-mcp

Step 2 — Start the server

Local-only quick start (default, safest):

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:

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:

winremote-mcp install

Step 3 — Connect OpenClaw

Add to your openclaw.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:

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

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:

{
  "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.

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

{
  "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:

[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.23

🐛 FastMCP debug/uvicorn compatibility

• Fixed winremote-mcp --debug with FastMCP 3.2.4+, where run_http_async renamed the uvicorn options keyword from uvicorn_args to uvicorn_config.
• winremote-mcp now detects the installed FastMCP signature and passes DEBUG uvicorn logging through the supported keyword, while preserving compatibility with older FastMCP releases.
• Added regression coverage so the debug HTTP startup path stays compatible with both keyword names.

Chinese release notes are available in [README.zh-CN.md](README.zh-CN.md).

What's New in v0.4.22

🐛 Debug flag restored

• Added the documented --debug CLI flag so winremote-mcp --debug is accepted.
• --debug enables DEBUG logging for winremote and passes log_level=debug to uvicorn for HTTP transport.

🔒 Dependency security updates

• Added minimum constraints for idna>=3.15 and starlette>=1.0.1 to avoid known vulnerable versions.

📚 README release notes cleanup

• README now keeps only the latest two What's New sections.
• Older release notes remain available in the full [CHANGELOG](CHANGELOG.md).

What's New in v0.4.21

📚 README release notes cleanup

• README keeps recent What's New sections focused and points older release notes to the full [CHANGELOG](CHANGELOG.md).

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)

pip install winremote-mcp

From Source

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

With Optional Dependencies

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

# 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

# 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

[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

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

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

Or in winremote.toml:

[server]
ssl_certfile = "/path/to/cert.pem"
ssl_keyfile  = "/path/to/key.pem"

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

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:

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

Or in winremote.toml:

[security]
oauth_client_id     = "my-client"
oauth_client_secret = "my-secret"

Claude Desktop config (claude_desktop_config.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

# 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):

{
  "mcpServers": {
    "winremote": {
      "command": "winremote-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}

For HTTP MCP clients:

{
  "mcpServers": {
    "winremote": {
      "type": "streamable-http", 
      "url": "http://192.168.1.100:8090/mcp",
      "headers": {
        "Authorization": "Bearer your-secret-key"
      }
    }
  }
}

Auto-Start on Boot

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

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

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dddabtc
• Source: dddabtc/winremote-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.