Winrdp MCP

winrdp-mcp

A zero-config [MCP](https://modelcontextprotocol.io) server that provisions and fully administers any Windows RDP box — Windows 10/11 and Server 2016–2025 — for Claude and Claude Code.

You give it a host and admin credentials. It makes the box remotely manageable *by itself* — turning on WinRM, opening the Windows firewall, and fixing local-admin token filtering — regardless of the box's starting state or Windows version. Claude then gets 156 tools: shell, files, registry, services, processes, scheduled tasks, users, firewall, event logs, software, networking, live RDP control, screenshots, GUI automation, real UAC elevation, one-call health/security reports, and on-demand tool staging — plus 6 guided workflows (prompts) and live host resources. Linux/macOS hosts are administered over SSH (run_sh, run_script(interpreter="sh")).

Nothing is pre-installed on the target. The controller reaches boxes over WinRM / SSH / SMB from wherever Claude Code runs, and manages one box or a whole fleet from a single server.

Why it's different

• Zero-config provisioning. provision_host climbs a ladder — WinRM → SSH → SMB/WMI cold-start → paste-once bootstrap — and makes a fresh, locked-down box manageable with no manual WinRM setup.
• Real UAC / elevation, not "please run as admin." Over WinRM a local admin gets a high-integrity full token and elevated ops run directly; a filtered token falls back to a one-shot SYSTEM Scheduled Task. as_user=True runs inside the interactive RDP desktop.
• 147 tools across 15 modules, every one with readOnlyHint / destructiveHint safety annotations so MCP clients can gate destructive actions automatically. Narrow the surface to a focused set with a tool profile (WINRDP_PROFILE=admin|rdp|core).
• Guided workflows & live context. 6 MCP prompts (provision_and_harden, diagnose_box, fix_connection, security_audit, setup_dev_box, open_service_locally) turn a whole operation into one click, and resources (winrdp://hosts, winrdp://host/{alias}/info) hand the model the inventory and a live box summary without spending a tool call.
• On-demand code execution. run_python finds or installs Python, pip-installs deps, runs your code, and cleans up — same for Node, PowerShell, cmd, and batch. stage_tool pulls Sysinternals (or any URL/local file) onto the box mid-task.
• Native GUI automation. Drive the interactive RDP desktop — keystrokes, mouse, and UI Automation (find/click/read controls by name) — plus live screenshots, with no on-box agent.
• One-call ops. health_report (OS/CPU/RAM/disk/services/errors/updates/Defender in one read), apply_baseline (high-perf power plan, no sleep, long paths), whoami_priv, failed_logons, list_open_ports.
• First-class RDP and an encrypted multi-host inventory (Fernet) with tags and parallel fan-out across the fleet.

Two modes, one package

Both build the *same* server; python -m winrdp_mcp serve is equivalent to the console script.

Table of contents

1. Quick start
2. Tool groups
3. Preparing a box
4. Key capabilities
5. Configuration
6. Security
7. Documentation
8. Architecture
9. Attribution & license

Quick start

1. Install

Python 3.10+ on the operator machine (Windows, macOS, or Linux). Targets are Windows.

pipx install winrdp-mcp              # isolated, recommended — gives you the `winrdp-mcp` command

uvx winrdp-mcp serve # zero-install run via uv pip install winrdp-mcp # plain pip

Optional extras and a local dev checkout:

pip install "winrdp-mcp[bootstrap]"  # + impacket, for SMB/WMI cold-start of boxes with WinRM AND SSH off

pip install "winrdp-mcp[agent-ui]" # + on-box interactive-desktop UI agent (click/type/OCR) pip install -e ".[dev]" # from a checkout of this repo (tests + ruff)

Claude Desktop, one click: grab winrdp-mcp.dxt from Releases and open it (Settings → Extensions → Install from file), or build it yourself with pwsh dxt/build.ps1.

2. Register with Claude Code

Drop a project .mcp.json at your repo root:

{

"mcpServers": { "winrdp": { "command": "winrdp-mcp", "args": ["serve"], "env": { "WINRDP_VAULT_KEY": "change-me", "WINRDP_PROFILE": "full" } } } }

Or register from the CLI:

claude mcp add winrdp -- winrdp-mcp serve

Set WINRDP_VAULT_KEY to a strong passphrase — it encrypts stored credentials at rest (see Configuration). Set WINRDP_PROFILE to admin, rdp, or core to expose a focused tool set instead of all 147.

3. The 30-second flow

Ask Claude to run these tools (arguments shown inline). Every tool takes an optional host= alias; omit it to hit the active host.

add_host  alias="vps1"  host="203.0.113.10"  username="Administrator"  password="…"

provision_host # climbs the ladder → box is now manageable system_info # OS, build, CPU, RAM, disks, IPs run_powershell script="Get-Service | Where Status -eq Running" run_python code="import platform; print(platform.platform())"

If the box has only RDP open, provision_host returns a bootstrap_oneliner to paste once into an RDP session — or call rdp_bootstrap, which copies that command to your clipboard and opens mstsc so you just paste it once. See Preparing a box.

Tool groups

147 tools across fifteen modules. The full catalog — every signature, parameter, default, and safety class — is in [docs/TOOLS.md](docs/TOOLS.md).

Safety classification across all 156: 55 read-only, 27 destructive, 74 mutating. Read-only tools are safe to auto-run; destructive tools carry destructiveHint=True so clients gate them behind confirmation.

Prompts & resources

Beyond tools, the server exposes MCP prompts (user-invoked, one-click operations that steer the model through the right tool sequence) and resources (bounded read-only context the client can hand the model for free):

Tool profiles

WINRDP_PROFILE selects which modules to expose, so the model's tool list stays focused:

`dynamic` is the recommended profile for large/long sessions: it follows the 2026 MCP guidance on tool-list bloat. Only ~41 core tools load up front; the model calls enable_toolset("rdp") (etc.) to