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

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 grow its tool list exactly when a task needs it, and disable_toolset(...) to shrink it again. Everything is still reachable — nothing is removed.

Preparing a box

The controller needs the target reachable on one management transport. In the best case (WinRM already up) provision_host does everything. The only two things you may have to do by hand on a brand-new cloud box are:

1. Open one management port inbound in the provider firewall / security group (5985 for WinRM-HTTP, or 5986 for HTTPS) — this is outside Windows and winrdp-mcp cannot do it for you.
2. Turn on a transport once — either paste the enable-WinRM one-liner into an RDP session, or let the SMB/WMI cold-start do it.

Print the paste-once one-liner any time:

winrdp-mcp bootstrap        # prints the -EncodedCommand one-liner + the readable script

Full walkthrough — provider-firewall specifics (AWS/Azure/GCP/Hetzner/…), the cold-start rungs, RDP hardening, verification, and a "new box in 3 minutes" runbook — in docs/PREPARE-SERVER.md.

Key capabilities

Provisioning ladder

provision_host tries the best rung first and stops at the first that works (winrdp_mcp/provision.py):

1. WinRM (5985/5986) reachable → use it, re-run the idempotent enable script to harden.
2. SSH (22) reachable → use it, and turn WinRM on over the SSH channel for the richer path.
3. SMB (445) + DCOM (135) only → stage the enable script over ADMIN$ and trigger it fire-and-forget over WMI ([bootstrap] extra), then switch to WinRM.
4. Nothing but RDP → return a bootstrap_oneliner to paste once; then everything is remote.

The enable script opens the WinRM firewall rule, flips a Public network profile to Private, and sets LocalAccountTokenFilterPolicy=1 so a non-builtin local admin gets a full token over the network.

Elevated & interactive execution

run_powershell  script="Stop-Service W3SVC"  elevated=true     # full unfiltered token
run_powershell  script="Add-Type -AssemblyName System.Windows.Forms; …"  as_user=true   # interactive RDP desktop

Over WinRM a full-token admin runs elevated=True directly (fast path); a filtered token (SSH / non-elevated local) falls back to a one-shot SYSTEM Scheduled Task. as_user=True runs inside the visible desktop session — needed for GUI, clipboard, and screenshots.

Run any script in one call

run_python  code="import psutil; print(psutil.cpu_percent())"  pip="psutil"   # auto-installs Python + psutil
run_script  content=<any code>  interpreter="auto"                            # python | node | powershell | cmd | vbscript
run_node    code="console.log(process.version)"
ensure_runtime  runtime="python"                                             # or "node"

run_python with ensure_python=True (default) locates Python or installs it detached (winget → choco → python.org), resolving the concrete python.exe by glob so it works the same session. Long installs run as a Scheduled Task and poll a done-marker, so a mid-install WinRM disconnect doesn't fail them.

Parallel fan-out across the fleet

add_host  alias="web1"  host="10.20.0.11"  username="Administrator"  password="…"  tags="prod,web"
run_on_hosts  script="(Get-CimInstance Win32_OperatingSystem).LastBootUpTime"  tag="prod"

run_on_hosts runs one script across many boxes concurrently (default max_parallel=8) and returns per-host {stdout, stderr, rc} keyed by alias. Select by aliases (CSV), by tag, or omit both to hit every box.

First-class RDP control

rdp_status                            # enabled? NLA? port? firewall?
rdp_enable  nla=true
rdp_sessions                          # id / user / state via qwinsta
screenshot                            # live RDP desktop as a PNG
rdp_open                              # launch mstsc pre-authenticated (operator = Windows)

rdp_connection_file generates a .rdp and stores the password via cmdkey on the operator machine — it is never returned to the model or written into the .rdp file. install_rdp_wrapper enables concurrent sessions on client SKUs.

On-demand tooling

stage_tool  source="psexec"                       # preset (Sysinternals), a URL, or a local file
stage_tool  source="https://example.com/tool.exe"
list_staged_tools
cleanup_staged

Presets: psexec, handle, procdump, autoruns, tcpview, pslist, accesschk, sigcheck. Everything caches under C:\ProgramData\winrdp-mcp\tools; URLs and presets download on the box, local files are uploaded.

Configuration

All configuration is via environment variables (set them in the env block of your .mcp.json).

Logging goes to stderr only — on the stdio transport, stdout is the MCP JSON-RPC channel. Known secrets are redacted from logs by exact match plus structural patterns.

Security

winrdp-mcp is admin tooling for boxes you own or are authorized to manage. It is a remote code-execution surface by design.

• Permissive first contact. Defaults favor zero-setup provisioning: winrm_cert_validation="ignore" and ssh_host_key_policy="auto" (trust-on-first-use). On an untrusted network this allows an on-path attacker to MITM. For production, register with add_host(..., use_ssl=true, winrm_port=5986, winrm_cert_validation="validate", ssh_host_key_policy="reject") and restrict the firewall to your operator IP.
• NTLM encrypts the payload over HTTP 5985. The default winrm_auth="ntlm" seals the message body even without TLS. The enable script deliberately does not turn on Basic/AllowUnencrypted/TrustedHosts=* (0.1.1+) — NTLM needs none of them, and they'd only weaken the box.
• Secrets on the box are transient. user_create / service_create stage the new password to an admin-only file read on the box (kept off the process command line / Event 4688); cmdkey stores the RDP password on the operator machine. None are ever returned to the model, and logs redact known secrets.
• Least privilege. Narrow the tool surface with WINRDP_ENABLED_TOOLS / WINRDP_DISABLED_TOOLS, and keep destructive-action confirmation on in your client.
• Behind a proxy/VPN that breaks NTLM? A rotating proxy (e.g. Clash in TUN mode) breaks connection-oriented NTLM — the multi-leg handshake needs one persistent TCP connection it won't preserve, so WinRM auth fails even with the right password (you'll see InvalidCredentials despite a valid login). Route the box IPs DIRECT in the proxy, or enable stateless Basic auth: rdp_bootstrap(enable_basic=True) (or enable_winrm(basic=True)) turns on Basic + AllowUnencrypted on the box, then register with add_host(..., winrm_auth="basic"). Basic over HTTP sends the password near-cleartext, so scope WinRM to your operator IP at the provider firewall.
• Server-side confirmation (optional). Set WINRDP_CONFIRM_DESTRUCTIVE=1 to make the server itself ask you to confirm (via MCP elicitation) before any destructive tool runs — a safety net for clients that don't gate on destructiveHint. Clients without elicitation support fall back to that client-side gating.

Full threat model, credential-vault internals, log redaction, argument-injection defenses, and a hardening checklist: docs/SECURITY.md.

Documentation

Architecture

winrdp-mcp is a FastMCP server: tools call a shared Context that resolves the target host from an encrypted vault, hands the PowerShell body to a cached Transport (WinRM / SSH / Local / SMB+WMI), and marshals delimited JSON back — nothing above the transport layer knows how the command reached the box. Full internals in docs/ARCHITECTURE.md.

Attribution & license

Built on and gratefully crediting two MIT-licensed projects — see NOTICE:

• winremote-mcp — basis for the on-box tool surface, the risk-tier model, and the optional deploy_ui_agent interactive-desktop path.
• windows-admin-mcp — basis for the WinRM-primary / SSH-fallback administration approach.

winrdp-mcp's own additions: the zero-config provisioning ladder, real UAC/elevation via one-shot Scheduled Tasks, on-demand tool staging, the encrypted multi-host inventory, and first-class RDP control.

MIT — see LICENSE and NOTICE.