{
  "markdown": "<!-- mcp-name: io.github.emog33k/winrdp-mcp -->\n\n# winrdp-mcp\n\n**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.**\n\n[![PyPI](https://img.shields.io/pypi/v/winrdp-mcp.svg)](https://pypi.org/project/winrdp-mcp/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/downloads/)\n[![Platform: Windows](https://img.shields.io/badge/Target-Windows%2010%2F11%20%7C%20Server%202016--2025-0078D6.svg)](#)\n[![MCP: FastMCP](https://img.shields.io/badge/MCP-FastMCP-6E56CF.svg)](https://github.com/jlowin/fastmcp)\n\nYou 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**.\n\n**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.\n\n### Why it's different\n\n- **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.\n- **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.\n- **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`).\n- **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.\n- **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.\n- **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.\n- **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`.\n- **First-class RDP** and an **encrypted multi-host inventory** (Fernet) with tags and parallel fan-out across the fleet.\n\n### Two modes, one package\n\n| Mode | Command | Runs where | Reaches the box via |\n|------|---------|-----------|---------------------|\n| **Controller** (default) | `winrdp-mcp serve` | wherever Claude Code lives | WinRM / SSH / SMB+DCOM |\n| **Agent** | `winrdp-mcp agent` | on the box itself | local PowerShell |\n\nBoth build the *same* server; `python -m winrdp_mcp serve` is equivalent to the console script.\n\n---\n\n## Table of contents\n\n1. [Quick start](#quick-start)\n2. [Tool groups](#tool-groups)\n3. [Preparing a box](#preparing-a-box)\n4. [Key capabilities](#key-capabilities)\n5. [Configuration](#configuration)\n6. [Security](#security)\n7. [Documentation](#documentation)\n8. [Architecture](#architecture)\n9. [Attribution & license](#attribution--license)\n\n---\n\n## Quick start\n\n### 1. Install\n\nPython **3.10+** on the operator machine (Windows, macOS, or Linux). Targets are Windows.\n\n```bash\npipx install winrdp-mcp              # isolated, recommended — gives you the `winrdp-mcp` command\nuvx winrdp-mcp serve                 # zero-install run via uv\npip install winrdp-mcp               # plain pip\n```\n\nOptional extras and a local dev checkout:\n\n```bash\npip install \"winrdp-mcp[bootstrap]\"  # + impacket, for SMB/WMI cold-start of boxes with WinRM AND SSH off\npip install \"winrdp-mcp[agent-ui]\"   # + on-box interactive-desktop UI agent (click/type/OCR)\npip install -e \".[dev]\"              # from a checkout of this repo (tests + ruff)\n```\n\n**Claude Desktop, one click:** grab `winrdp-mcp.dxt` from [Releases](https://github.com/emog33k/winrdp-mcp/releases) and open it (Settings → Extensions → Install from file), or build it yourself with `pwsh dxt/build.ps1`.\n\n### 2. Register with Claude Code\n\nDrop a project `.mcp.json` at your repo root:\n\n```json\n{\n  \"mcpServers\": {\n    \"winrdp\": {\n      \"command\": \"winrdp-mcp\",\n      \"args\": [\"serve\"],\n      \"env\": { \"WINRDP_VAULT_KEY\": \"change-me\", \"WINRDP_PROFILE\": \"full\" }\n    }\n  }\n}\n```\n\nOr register from the CLI:\n\n```bash\nclaude mcp add winrdp -- winrdp-mcp serve\n```\n\nSet `WINRDP_VAULT_KEY` to a strong passphrase — it encrypts stored credentials at rest (see [Configuration](#configuration)). Set `WINRDP_PROFILE` to `admin`, `rdp`, or `core` to expose a focused tool set instead of all 144.\n\n### 3. The 30-second flow\n\nAsk Claude to run these tools (arguments shown inline). Every tool takes an optional `host=` alias; omit it to hit the **active** host.\n\n```text\nadd_host  alias=\"vps1\"  host=\"203.0.113.10\"  username=\"Administrator\"  password=\"…\"\nprovision_host                        # climbs the ladder → box is now manageable\nsystem_info                           # OS, build, CPU, RAM, disks, IPs\nrun_powershell  script=\"Get-Service | Where Status -eq Running\"\nrun_python  code=\"import platform; print(platform.platform())\"\n```\n\nIf the box has only RDP open, `provision_host` returns a `bootstrap_oneliner` to paste once into an RDP session — see [Preparing a box](#preparing-a-box).\n\n---\n\n## Tool groups\n\n**144 tools** across fifteen modules. The full catalog — every signature, parameter, default, and safety class — is in **[docs/TOOLS.md](docs/TOOLS.md)**.\n\n| Group | Module | # | What it covers |\n|-------|--------|--:|----------------|\n| **Hosts & Fleet** | `hosts.py` | 8 | `add_host`, `list_hosts`, `use_host`, `remove_host`, `test_host`, `provision_host`, `run_on_hosts` (parallel fan-out), `reboot_and_wait` |\n| **Provisioning / UAC / Tooling** | `provisioning.py` | 10 | `enable_winrm`, `enable_ssh`, `run_elevated`, `uac_get`/`uac_set`, `stage_tool`, `stage_script`, `list_staged_tools`, `cleanup_staged`, `deploy_ui_agent` |\n| **System** | `system.py` | 8 | `run_powershell`, `run_cmd`, `system_info`, `performance`, `event_log`, `screenshot`, `reboot`, `power_action` |\n| **Scripting** | `scripting.py` | 6 | `run_python`, `run_python_file`, `pip_install`, `run_script` (auto-interpreter), `run_node`, `ensure_runtime` |\n| **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` |\n| **Admin** | `admin.py` | 25 | registry, services (`service_control`/`service_create`/`service_delete`), processes, scheduled tasks, users/groups, firewall, clipboard, event-log write/clear |\n| **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` |\n| **Software** | `software.py` | 4 | `install_software` (winget/choco/MSI/EXE-url), `uninstall_software`, `list_installed_software`, `ensure_package_manager` |\n| **Network** | `network.py` | 8 | `net_info`, `ping`, `port_check`, `net_connections`, `port_proxy_add`/`list`/`delete` (tunneling), `set_dns` |\n| **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` |\n| **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` |\n| **Waiters** | `waiters.py` | 4 | `wait_for_port`, `wait_for_service`, `wait_for_process`, `wait_for_file` — block until a condition holds |\n| **Scheduling** | `scheduling.py` | 4 | `schedule_command`, `run_at_startup`, `persist_as_service` (NSSM auto-restart), `unpersist_service` |\n| **Tunnel** | `tunnel.py` | 3 | `port_forward`, `port_forward_stop`, `port_forward_list` — SSH local-forward a box's service to your machine |\n| **Ops** | `ops.py` | 5 | `health_report`, `apply_baseline`, `whoami_priv`, `failed_logons`, `list_open_ports` — one-call health & security reads |\n\nSafety 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.\n\n### Prompts & resources\n\nBeyond 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):\n\n| Kind | Name | What it does |\n|------|------|--------------|\n| Prompt | `provision_and_harden(host, username, password, alias)` | Bring a new box under management and lock it down, step by step |\n| Prompt | `diagnose_box(host)` | Gather health evidence and give a prioritized root-cause summary |\n| Prompt | `security_audit(host)` | Read-only posture review → risk-ranked findings + remediations |\n| Prompt | `setup_dev_box(host, runtimes)` | Install runtimes/tools and verify a working dev environment |\n| Prompt | `open_service_locally(host, remote_port, note)` | Reach a box's loopback service from your machine over an SSH tunnel |\n| Resource | `winrdp://hosts` | The registered inventory (passwords redacted) + active host |\n| Resource | `winrdp://host/{alias}/info` | A compact live summary of one box (OS, build, CPU/RAM, disks, uptime) |\n\n### Tool profiles\n\n`WINRDP_PROFILE` selects which modules to expose, so the model's tool list stays focused:\n\n| Profile | Tools | Includes |\n|---------|------:|----------|\n| `full` (default) | 144 | everything |\n| `admin` | 117 | systems administration (no GUI/RDP-desktop, no bare tunnel) |\n| `rdp` | 104 | RDP + desktop/GUI focus |\n| `core` | 87 | the essential subset (hosts, provisioning, system, scripting, files, admin, ops, waiters) |\n\n---\n\n## Preparing a box\n\nThe 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:\n\n1. **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.\n2. **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.\n\nPrint the paste-once one-liner any time:\n\n```bash\nwinrdp-mcp bootstrap        # prints the -EncodedCommand one-liner + the readable script\n```\n\nFull 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](docs/PREPARE-SERVER.md)**.\n\n---\n\n## Key capabilities\n\n### Provisioning ladder\n\n`provision_host` tries the best rung first and stops at the first that works ([`winrdp_mcp/provision.py`](winrdp_mcp/provision.py)):\n\n1. **WinRM** (5985/5986) reachable → use it, re-run the idempotent enable script to harden.\n2. **SSH** (22) reachable → use it, and turn WinRM on over the SSH channel for the richer path.\n3. **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.\n4. **Nothing but RDP** → return a `bootstrap_oneliner` to paste once; then everything is remote.\n\nThe 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.\n\n### Elevated & interactive execution\n\n```text\nrun_powershell  script=\"Stop-Service W3SVC\"  elevated=true     # full unfiltered token\nrun_powershell  script=\"Add-Type -AssemblyName System.Windows.Forms; …\"  as_user=true   # interactive RDP desktop\n```\n\nOver 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.\n\n### Run any script in one call\n\n```text\nrun_python  code=\"import psutil; print(psutil.cpu_percent())\"  pip=\"psutil\"   # auto-installs Python + psutil\nrun_script  content=<any code>  interpreter=\"auto\"                            # python | node | powershell | cmd | vbscript\nrun_node    code=\"console.log(process.version)\"\nensure_runtime  runtime=\"python\"                                             # or \"node\"\n```\n\n`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.\n\n### Parallel fan-out across the fleet\n\n```text\nadd_host  alias=\"web1\"  host=\"10.20.0.11\"  username=\"Administrator\"  password=\"…\"  tags=\"prod,web\"\nrun_on_hosts  script=\"(Get-CimInstance Win32_OperatingSystem).LastBootUpTime\"  tag=\"prod\"\n```\n\n`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.\n\n### First-class RDP control\n\n```text\nrdp_status                            # enabled? NLA? port? firewall?\nrdp_enable  nla=true\nrdp_sessions                          # id / user / state via qwinsta\nscreenshot                            # live RDP desktop as a PNG\nrdp_open                              # launch mstsc pre-authenticated (operator = Windows)\n```\n\n`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.\n\n### On-demand tooling\n\n```text\nstage_tool  source=\"psexec\"                       # preset (Sysinternals), a URL, or a local file\nstage_tool  source=\"https://example.com/tool.exe\"\nlist_staged_tools\ncleanup_staged\n```\n\nPresets: `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.\n\n---\n\n## Configuration\n\nAll configuration is via environment variables (set them in the `env` block of your `.mcp.json`).\n\n| Variable | Purpose |\n|----------|---------|\n| `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.** |\n| `WINRDP_HOME` | Override the data directory holding `inventory.json` and `vault.key` (default `%APPDATA%\\winrdp-mcp`). |\n| `WINRDP_DEBUG` | `1`/`true`/`yes` → verbose DEBUG logging to **stderr** (equivalent to `--debug`). |\n| `WINRDP_PROFILE` | Tool profile to expose: `full` (default, 144), `admin` (117), `rdp` (104), or `core` (87). |\n| `WINRDP_ENABLED_TOOLS` | CSV allowlist — if set, **only** these tools are registered. |\n| `WINRDP_DISABLED_TOOLS` | CSV blocklist — these tools are skipped (e.g. `reboot,file_delete`). |\n| `WINRDP_WINRM_OP_TIMEOUT` | WinRM per-operation timeout in seconds (default `180`; read timeout is derived as `+30`). |\n\nLogging 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.\n\n---\n\n## Security\n\nwinrdp-mcp is admin tooling for boxes **you own or are authorized to manage**. It is a remote code-execution surface by design.\n\n- **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.\n- **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.\n- **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.\n- **Least privilege.** Narrow the tool surface with `WINRDP_ENABLED_TOOLS` / `WINRDP_DISABLED_TOOLS`, and keep destructive-action confirmation on in your client.\n\nFull threat model, credential-vault internals, log redaction, argument-injection defenses, and a hardening checklist: **[docs/SECURITY.md](docs/SECURITY.md)**.\n\n---\n\n## Documentation\n\n| Doc | Contents |\n|-----|----------|\n| **[docs/PREPARE-SERVER.md](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. |\n| **[docs/PRODUCTION.md](docs/PRODUCTION.md)** | Running safely at scale: install options, vault, transport hardening, allow/block lists, observability, reliability, fleet management, background-service setup, checklist. |\n| **[docs/SECURITY.md](docs/SECURITY.md)** | Threat model, trust boundary, credential handling, transport/MITM, the enable-WinRM script, argument-injection defense, hardening checklist. |\n| **[docs/TROUBLESHOOTING.md](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). |\n| **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** | Internal map for contributors: transports → PowerShell marshaling → provisioning → elevation → context → vault → tooling → server assembly. |\n| **[docs/TOOLS.md](docs/TOOLS.md)** | The complete reference for all 144 tools — signatures, parameters, defaults, and safety class. |\n\n---\n\n## Architecture\n\nwinrdp-mcp is a [FastMCP](https://github.com/jlowin/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](docs/ARCHITECTURE.md)**.\n\n---\n\n## Attribution & license\n\nBuilt on and gratefully crediting two MIT-licensed projects — see [NOTICE](NOTICE):\n\n- **[winremote-mcp](https://github.com/dddabtc/winremote-mcp)** — basis for the on-box tool surface, the risk-tier model, and the optional `deploy_ui_agent` interactive-desktop path.\n- **[windows-admin-mcp](https://github.com/Cosmicjedi/windows-admin-mcp)** — basis for the WinRM-primary / SSH-fallback administration approach.\n\nwinrdp-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.\n\n**MIT** — see [LICENSE](LICENSE) and [NOTICE](NOTICE).\n",
  "bytes": 20620,
  "sha": "458ac228ac96e03ca90f0168549a323131669d3788c1614ddb75c88f2fae4b83",
  "repo_slug": "emog33k/winrdp-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_emog33k_winrdp_mcp_07877f6f/readme"
}