winrdp-mcp

A zero-config MCP 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 144 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 5 guided workflows (prompts) and live host resources.

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.
• 144 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. 5 MCP prompts (provision_and_harden, diagnose_box, 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 144.

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 — see Preparing a box.

Tool groups

144 tools across fifteen modules. The full catalog — every signature, parameter, default, and safety class — is in docs/TOOLS.md.

Safety classification across all 144: 49 read-only, 23 destructive, 72 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):