winremote

WinRemote MCP is a Python-based MCP server that exposes a powerful remote Windows automation endpoint. It runs on the Windows machine you want to control and exposes a rich set of tools for desktop control, window management, remote shell access, file operations, and broader system administration, all accessible via the Model Context Protocol (MCP). Clients such as Claude Desktop or OpenClaw can send MCP requests to execute PowerShell/CMD commands, capture screenshots, read or write files, manage windows, and even run registry or service tasks. The server supports tiered tool access (Tier 1-3) with sensible defaults and optional authentication to limit exposure. You can also run it in no-auth mode for trusted LAN environments.

To use WinRemote MCP, start the server on the target Windows machine, for example with:

pip install winremote-mcp
winremote-mcp --port 8090

Once running, clients can connect via HTTP/streamable MCP endpoints or via standard MCP clients. The server can be configured to allow or restrict specific tools, manage access through an API key, and be bound to localhost or external interfaces as needed. Features include desktop screenshots (with multi-monitor support), GUI automation (mouse clicks, keystrokes, window focus), remote PowerShell/CMD execution, file operations (read/write/list/search with base64 transfer), registry access, service and task management, network utilities (ping, port checks), OCR text extraction, and screen recording with labeled annotations.

This MCP server is designed to integrate with AI agents and automation frameworks, enabling remote agents to interact with a Windows desktop as if they were local users, while preserving security and control through tiered access and optional authentication.

Prerequisites:

• A Windows machine (the target for control) with Python installed (3.8+ recommended).
• Internet access to install Python packages unless installing from source.

Install from PyPI (recommended):

pip install winremote-mcp

Run the server (default port 8090):

winremote-mcp --port 8090

If you prefer running via Python module (useful for custom environments):

python -m winremote_mcp --port 8090

From Source (optional):

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

Optional dependencies and features:

# Optional OCR support
pip install winremote-mcp[ocr]

OCR setup (optional):

winget install UB-Mannheim.TesseractOCR
pip install winremote-mcp[ocr]

Configuration tips:

• To expose on all interfaces and enable authentication: winremote-mcp --host 0.0.0.0 --port 8090 --auth-key "your-secret-key"
• To run without authentication in a trusted LAN: winremote-mcp --port 8090 --no-auth
• For auto-start on boot or Windows Task Scheduler, use the provided install/uninstall helpers in the toolset.

Verification:

# Simple health/health-check style request can be performed by your MCP client
# or by hitting the server root if supported by your client setup.
curl http://127.0.0.1:8090/mcp

Tips and common issues:

• By default, access may be localhost-only. Use --host 0.0.0.0 to expose on the network, but enable authentication with --auth-key to secure access.
• Tools are organized into Tier 1 (read-only), Tier 2 (interactive), and Tier 3 (destructive). The server starts with Tier 1-2 enabled; enable Tier 3 only when necessary and in trusted networks.
• If you plan to integrate with OpenClaw or other MCP clients, ensure the client configuration points to http://<WINDOWS_IP>:8090/mcp and uses the appropriate transport (stdio or HTTP-based streams).
• For OCR support, ensure Tesseract is installed and the optional dependency is installed via pip.
• When running behind a firewall, open port 8090 (or your chosen port) and consider using a secure (TLS) proxy if exposing to the internet.
• If you encounter issues with tool availability, you can override tool sets at startup with flags like --enable-all, --disable-tier2, or --tools to explicitly list capabilities.