winrdp-mcp

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

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

Mode	Command	Runs where	Reaches the box via
Controller (default)	winrdp-mcp serve	wherever Claude Code lives	WinRM / SSH / SMB+DCOM
Agent	winrdp-mcp agent	on the box itself	local PowerShell

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.

Group	Module	#	What it covers
Hosts & Fleet	hosts.py	9	add_host, list_hosts, use_host, remove_host, test_host, diagnose_host, provision_host, run_on_hosts (parallel fan-out), reboot_and_wait
Provisioning / UAC / Tooling	provisioning.py	11	enable_winrm, enable_ssh, run_elevated, uac_get/uac_set, stage_tool, stage_script, list_staged_tools, cleanup_staged, deploy_ui_agent, rdp_bootstrap
System	system.py	8	run_powershell, run_cmd, system_info, performance, event_log, screenshot, reboot, power_action
Scripting	scripting.py	6	run_python, run_python_file, pip_install, run_script (auto-interpreter), run_node, ensure_runtime
Files	files.py	21	list/read/write/search/upload/download/delete, make_dir, copy/move, file_hash, zip/unzip, ACL, download_file, tail_file, edit_file, sync_folder, transfer_between_hosts
Admin	admin.py	25	registry, services (service_control/service_create/service_delete), processes, scheduled tasks, users/groups, firewall, clipboard, event-log write/clear
RDP	rdp.py	12	rdp_status/rdp_enable/rdp_disable/rdp_set_port, sessions, disconnect/logoff, rdp_connect_to_console (tscon), rdp_connection_file, rdp_open, install_rdp_wrapper, rdp_allow_multiple_sessions
Software	software.py	4	install_software (winget/choco/MSI/EXE-url), uninstall_software, list_installed_software, ensure_package_manager
Network	network.py	8	net_info, ping, port_check, net_connections, port_proxy_add/list/delete (tunneling), set_dns
Windows	windows.py	11	cim_query (any WQL), windows_features, windows_update, hotfixes, Defender (status/realtime/exclusion_add/scan), env_get/env_set, list_startup
GUI	gui.py	15	windows/keyboard/mouse (send_keys, type_text, mouse_click, mouse_drag), UI Automation (ui_find/ui_invoke/ui_set_text), ocr_screen, find_and_click, wait_for_window, record_screen, gui_script
Waiters	waiters.py	4	wait_for_port, wait_for_service, wait_for_process, wait_for_file — block until a condition holds
Scheduling	scheduling.py	5	schedule_command, run_at_startup, persist_as_service (NSSM auto-restart), unpersist_service, task_stop
Tunnel	tunnel.py	3	port_forward, port_forward_stop, port_forward_list — SSH local-forward a box's service to your machine
Ops	ops.py	5	health_report, apply_baseline, whoami_priv, failed_logons, list_open_ports — one-call health & security reads

Safety classification across all 147: 50 read-only, 24 destructive, 73 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):

Kind	Name	What it does
Prompt	provision_and_harden(host, username, password, alias)	Bring a new box under management and lock it down, step by step
Prompt	diagnose_box(host)	Gather health evidence and give a prioritized root-cause summary
Prompt	fix_connection(host)	Figure out why a box won't connect (via diagnose_host) and get it working
Prompt	security_audit(host)	Read-only posture review → risk-ranked findings + remediations
Prompt	setup_dev_box(host, runtimes)	Install runtimes/tools and verify a working dev environment
Prompt	open_service_locally(host, remote_port, note)	Reach a box's loopback service from your machine over an SSH tunnel
Resource	winrdp://hosts	The registered inventory (passwords redacted) + active host
Resource	winrdp://host/{alias}/info	A compact live summary of one box (OS, build, CPU/RAM, disks, uptime)

Tool profiles

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

Profile	Tools	Includes
full (default)	147	everything
dynamic	44 at start	lean core + list_toolsets/enable_toolset/disable_toolset; the model pulls in groups (rdp, gui, network, …) on demand
admin	120	systems administration (no GUI/RDP-desktop, no bare tunnel)
rdp	106	RDP + desktop/GUI focus
core	89	the essential subset (hosts, provisioning, system, scripting, files, admin, ops, waiters)

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

Variable	Purpose
WINRDP_VAULT_KEY	Passphrase (or raw Fernet key) that encrypts stored passwords. A passphrase is SHA-256-derived into a key. If unset, a machine-local vault.key (owner-only) is generated. Set it.
WINRDP_HOME	Override the data directory holding inventory.json and vault.key (default %APPDATA%\winrdp-mcp).
WINRDP_DEBUG	1/true/yes → verbose DEBUG logging to stderr (equivalent to --debug).
WINRDP_PROFILE	Tool profile to expose: full (default, 147), admin (120), rdp (106), or core (89).
WINRDP_ENABLED_TOOLS	CSV allowlist — if set, only these tools are registered.
WINRDP_DISABLED_TOOLS	CSV blocklist — these tools are skipped (e.g. reboot,file_delete).
WINRDP_WINRM_OP_TIMEOUT	WinRM per-operation timeout in seconds (default 180; read timeout is derived as +30).

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

Doc	Contents
docs/PREPARE-SERVER.md	Taking a fresh cloud/VDS/dedicated box from locked-down to managed: provider firewalls, cold-start options, RDP hardening, verification, sizing.
docs/PRODUCTION.md	Running safely at scale: install options, vault, transport hardening, allow/block lists, observability, reliability, fleet management, background-service setup, checklist.
docs/SECURITY.md	Threat model, trust boundary, credential handling, transport/MITM, the enable-WinRM script, argument-injection defense, hardening checklist.
docs/TROUBLESHOOTING.md	Symptom → cause → fix for the failure modes you actually hit (provision failures, connection drops, slow elevation, Python/Node install, SSH banner, 5986 certs, MCP registration).
docs/ARCHITECTURE.md	Internal map for contributors: transports → PowerShell marshaling → provisioning → elevation → context → vault → tooling → server assembly.
docs/TOOLS.md	The complete reference for all 147 tools — signatures, parameters, defaults, and safety class.

---

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.