winrdp-mcp

winrdp-mcp

零配置 MCP 服务，可为 Claude 和 Claude Code 配置并全面管理任意 Windows RDP 计算机 — Windows 10/11 和 Server 2016–2025。

只需提供主机和管理员凭据，它就能让计算机自行支持远程管理 — 开启 WinRM、开放 Windows 防火墙并修复本地管理员令牌筛选，无论计算机的初始状态或 Windows 版本如何。随后，Claude 将获得 147 个工具：Shell、文件、注册表、服务、进程、计划任务、用户、防火墙、事件日志、软件、网络、实时 RDP 控制、屏幕截图、GUI 自动化、真正的 UAC 提权、一键健康与安全报告，以及按需工具部署 — 另有 6 个引导式工作流（提示词）和实时主机资源。

目标计算机上无需预先安装任何内容。 控制器通过 WinRM / SSH / SMB 连接计算机，连接来源可以是 Claude Code 的运行位置；并且可通过单个服务管理一台计算机或整个机群。

它的不同之处

• 零配置部署。 provision_host 按顺序尝试 WinRM → SSH → SMB/WMI 冷启动 → 一次性粘贴引导程序，让全新且安全锁定的计算机无需手动设置 WinRM 即可接受管理。
• 真正的 UAC / 提权，而非“请以管理员身份运行”。 通过 WinRM 操作时，本地管理员可获得高完整性完整令牌，提权操作直接运行；如果令牌经过筛选，则回退到一次性 SYSTEM 计划任务。as_user=True 会在交互式 RDP 桌面中运行。
• 15 个模块中的 147 个工具，每个工具都带有 readOnlyHint / destructiveHint 安全注释，MCP 客户端可据此自动限制破坏性操作。使用工具配置（WINRDP_PROFILE=admin|rdp|core）可将工具范围缩小为一组专用工具。
• 引导式工作流与实时上下文。 6 个 MCP 提示词（provision_and_harden、diagnose_box、fix_connection、security_audit、setup_dev_box、open_service_locally）可一键完成整个操作；资源（winrdp://hosts、winrdp://host/{alias}/info）可将资产清单和实时计算机摘要交给模型，无需消耗工具调用。
• 按需执行代码。 run_python 会查找或安装 Python、通过 pip 安装依赖、运行代码并清理；Node、PowerShell、cmd 和 batch 也同样适用。stage_tool 可在任务进行中将 Sysinternals（或任意 URL / 本地文件）下载到计算机。
• 原生 GUI 自动化。 无需在计算机上运行 Agent，即可操控交互式 RDP 桌面 — 使用按键、鼠标和 UI Automation（按名称查找 / 点击 / 读取控件）— 并查看实时屏幕截图。
• 一键运维。 health_report（一次读取 OS / CPU / RAM / 磁盘 / 服务 / 错误 / 更新 / Defender）、apply_baseline（高性能电源计划、不休眠、长路径）、whoami_priv、failed_logons、list_open_ports。
• 一流的 RDP 支持和加密的多主机资产清单（Fernet），支持标签及在整个机群中并行分发操作。

两种模式，一个软件包

模式	命令	运行位置	连接计算机的方式
控制器（默认）	winrdp-mcp serve	Claude Code 所在位置	WinRM / SSH / SMB+DCOM
Agent	winrdp-mcp agent	计算机本身	本地 PowerShell

两种模式构建的是同一个服务；python -m winrdp_mcp serve 等同于控制台脚本。

---

目录

1. 快速开始
2. 工具组
3. 准备一台主机
4. 关键功能
5. 配置
6. 安全
7. 文档
8. 架构
9. 致谢与许可

---

快速开始

1. 安装

操作端机器需要安装 Python 3.10+（Windows、macOS 或 Linux）。目标系统为 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

可选扩展和本地开发检出：

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，一键安装：**从 Releases 下载 winrdp-mcp.dxt 并打开（Settings → Extensions → Install from file），或者使用 pwsh dxt/build.ps1 自行构建。

2. 注册到 Claude Code

在仓库根目录放置项目 .mcp.json：

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

或者从命令行注册：

claude mcp add winrdp -- winrdp-mcp serve

将 WINRDP_VAULT_KEY 设置为强密码短语——它会对静态存储的凭据进行加密（参见配置）。将 WINRDP_PROFILE 设置为 admin、rdp 或 core，以启用一组精简的工具，而不是全部 147 个工具。

3. 30 秒工作流

让 Claude 运行这些工具（参数以内联形式显示）。每个工具都接受可选的 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())"

如果主机只开放了 RDP，provision_host 会返回一个 bootstrap_oneliner，供你在 RDP 会话中粘贴一次；或者调用 rdp_bootstrap，它会将该命令复制到剪贴板并打开 mstsc，这样你只需粘贴一次即可。参见准备一台主机。

---

工具分组

147 个工具，分布在 15 个模块中。完整目录——包含每个签名、参数、默认值和安全类别——请参阅 docs/TOOLS.md。

分组	模块	#	涵盖内容
主机与机群	hosts.py	9	add_host、list_hosts、use_host、remove_host、test_host、diagnose_host、provision_host、run_on_hosts（并行扇出）、reboot_and_wait
配置 / UAC / 工具	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.py	8	run_powershell、run_cmd、system_info、performance、event_log、screenshot、reboot、power_action
脚本编写	scripting.py	6	run_python、run_python_file、pip_install、run_script（自动选择解释器）、run_node、ensure_runtime
文件	files.py	21	列出/读取/写入/搜索/上传/下载/删除、make_dir、复制/移动、file_hash、压缩/解压、ACL、download_file、tail_file、edit_file、sync_folder、transfer_between_hosts
管理	admin.py	25	注册表、服务（service_control/service_create/service_delete）、进程、计划任务、用户/组、防火墙、剪贴板、事件日志写入/清除
RDP	rdp.py	12	rdp_status/rdp_enable/rdp_disable/rdp_set_port、会话、断开连接/注销、rdp_connect_to_console（tscon）、rdp_connection_file、rdp_open、install_rdp_wrapper、rdp_allow_multiple_sessions
软件	software.py	4	install_software（winget/choco/MSI/EXE-url）、uninstall_software、list_installed_software、ensure_package_manager
网络	network.py	8	net_info、ping、port_check、net_connections、port_proxy_add/list/delete（隧道）、set_dns
Windows	windows.py	11	cim_query（任意 WQL）、windows_features、windows_update、hotfixes、Defender（status/realtime/exclusion_add/scan）、env_get/env_set、list_startup
GUI	gui.py	15	窗口/键盘/鼠标（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.py	4	wait_for_port、wait_for_service、wait_for_process、wait_for_file——阻塞等待条件成立
调度	scheduling.py	5	schedule_command、run_at_startup、persist_as_service（NSSM 自动重启）、unpersist_service、task_stop
隧道	tunnel.py	3	port_forward、port_forward_stop、port_forward_list——通过 SSH 本地转发，将主机上的服务转发到你的计算机
运维	ops.py	5	health_report、apply_baseline、whoami_priv、failed_logons、list_open_ports——一键读取运行状况与安全信息

全部 147 个工具的安全分类：50 个只读、24 个破坏性、73 个有修改操作。只读工具可安全地自动运行；破坏性工具带有 destructiveHint=True，客户端会要求确认后才允许执行。

提示词与资源

除了工具外，服务器还会公开 MCP 提示词（由用户调用的一键操作，引导模型按正确顺序使用工具）和资源（有界的只读上下文，客户端可免费提供给模型）：

类型	名称	作用
提示词	provision_and_harden(host, username, password, alias)	逐步将新主机纳入管理并加固安全
提示词	diagnose_box(host)	收集运行状况证据，并提供按优先级排序的根因摘要
提示词	fix_connection(host)	找出主机无法连接的原因（通过 diagnose_host），并修复连接
提示词	security_audit(host)	只读安全态势审查 → 按风险排序的发现结果及修复措施
提示词	setup_dev_box(host, runtimes)	安装运行时和工具，并验证开发环境是否正常工作
提示词	open_service_locally(host, remote_port, note)	通过 SSH 隧道，从本机访问主机的回环服务
资源	winrdp://hosts	已注册的主机清单（密码已隐藏）及当前活动主机
资源	winrdp://host/{alias}/info	单台主机的精简实时摘要（操作系统、版本、CPU/RAM、磁盘、运行时间）

工具配置

WINRDP_PROFILE 用于选择要公开的模块，让模型的工具列表保持精简：

配置	工具数	包含内容
full（默认）	147	全部内容
dynamic	启动时 44 个	精简核心工具 + list_toolsets/enable_toolset/disable_toolset；模型按需加载工具组（rdp、gui、network 等）
admin	120	系统管理（不含 GUI/RDP 桌面和裸隧道）
rdp	106	专注于 RDP + 桌面/GUI
core	89	核心子集（主机、配置、系统、脚本、文件、管理、运维、等待器）

对于大型或长时间会话，推荐使用 dynamic 配置：它遵循 2026 年 MCP 关于工具列表膨胀的指导原则。启动时仅加载约 41 个核心工具；模型会在任务需要时调用 enable_toolset("rdp")（等）来扩展工具列表，并通过 disable_toolset(...) 再次缩减。所有功能仍然可用——没有任何功能被移除。

---

准备主机

控制器需要通过一种管理传输方式连接到目标主机。理想情况下（WinRM 已启用），provision_host 会完成所有操作。对于全新的云主机，你可能需要手动完成的只有以下两件事：

1. 在云服务商防火墙/安全组中开放一个入站管理端口（WinRM-HTTP 使用 5985，HTTPS 使用 5986）——这一步在 Windows 之外，winrdp-mcp 无法替你完成。
2. 启用一种传输方式——要么在 RDP 会话中粘贴启用 WinRM 的单行命令，要么通过 SMB/WMI 冷启动完成。

随时可以打印这条只需粘贴一次的单行命令：

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

完整操作指南——包括云服务商防火墙细节（AWS/Azure/GCP/Hetzner/……）、冷启动步骤、RDP 加固、验证，以及“3 分钟启动新主机”运行手册——请参阅 docs/PREPARE-SERVER.md。

---

核心功能

配置阶梯

provision_host 会先尝试最佳方案，并在首个成功方案处停止（winrdp_mcp/provision.py）：

1. WinRM（可连接 5985/5986）→ 使用它，并重新运行幂等启用脚本以加固安全。
2. SSH（可连接 22）→ 使用它，并通过 SSH 通道启用 WinRM，以使用功能更丰富的方案。
3. 仅有 SMB（445）+ DCOM（135） → 通过 ADMIN$ 暂存启用脚本，并通过 WMI 以即发即弃的方式触发脚本（需附加项 [bootstrap]），然后切换到 WinRM。
4. 只有 RDP → 返回 bootstrap_oneliner，粘贴一次即可；之后所有操作都可远程完成。

启用脚本会开放 WinRM 防火墙规则，将 Public 网络配置文件切换为 Private，并设置 LocalAccountTokenFilterPolicy=1，以便非内置本地管理员通过网络获得完整令牌。

提权与交互式执行

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

通过 WinRM 运行且拥有完整令牌的管理员会直接运行 elevated=True（快速路径）；筛选令牌（SSH / 未提权的本地令牌）则会回退到一次性 SYSTEM 计划任务。as_user=True 会在可见的桌面会话中运行——GUI、剪贴板和屏幕截图都需要此设置。

一次调用运行任意脚本

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"

启用 ensure_python=True（默认值）的 run_python 会查找 Python，或在后台安装 Python（winget → choco → python.org），并通过 glob 查找具体的 python.exe，以便在同一会话中正常运行。耗时较长的安装会作为计划任务运行，并轮询完成标记，因此安装过程中 WinRM 中断也不会导致任务失败。

在整个设备群中并行执行

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 会在多台设备上并发运行同一脚本（默认 max_parallel=8），并按别名返回每台主机对应的 {stdout, stderr, rc}。可通过 aliases（CSV）或 tag 选择主机，也可以省略两者以对所有设备执行操作。

一流的 RDP 控制

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 会生成 .rdp 文件，并通过 cmdkey 在操作员计算机上保存密码——密码绝不会返回给模型，也不会写入 .rdp 文件。install_rdp_wrapper 可在客户端 SKU 上启用并发会话。

按需工具

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

预设：psexec, handle, procdump, autoruns, tcpview, pslist, accesschk, sigcheck。所有内容都会缓存到 C:\ProgramData\winrdp-mcp\tools；URL 和预设会在目标设备上下载，本地文件则会上传。

---

配置

所有配置均通过环境变量完成（在 .mcp.json 的 env 块中设置）。

变量	用途
WINRDP_VAULT_KEY	用于加密已存储密码的口令（或原始 Fernet 密钥）。口令会通过 SHA-256 派生为密钥。如果未设置，则会生成仅所有者可访问的本机 vault.key。请设置此项。
WINRDP_HOME	覆盖用于存放 inventory.json 和 vault.key 的数据目录（默认 %APPDATA%\winrdp-mcp）。
WINRDP_DEBUG	1/true/yes → 将详细的 DEBUG 日志写入标准错误（等同于 --debug）。
WINRDP_PROFILE	要公开的工具配置：full（默认值，147）、admin（120）、rdp（106）或 core（89）。
WINRDP_ENABLED_TOOLS	CSV 允许列表——如果设置，则仅注册这些工具。
WINRDP_DISABLED_TOOLS	CSV 阻止列表——跳过其中的工具（例如 reboot,file_delete）。
WINRDP_WINRM_OP_TIMEOUT	WinRM 每项操作的超时时间（秒；默认 180；读取超时基于此值加 30 得出）。

日志仅写入标准错误——在 stdio 传输中，标准输出是 MCP JSON-RPC 通道。日志会通过精确匹配和结构化模式对已知机密进行脱敏。

---

安全

winrdp-mcp 是用于管理你拥有或获准管理的计算机的管理员工具，按设计提供远程代码执行能力。

• 首次连接时采取宽松策略。 默认设置优先实现零配置部署：winrm_cert_validation="ignore" 和 ssh_host_key_policy="auto"（首次使用时信任）。在不可信网络上，这会使中间人攻击者能够实施 MITM。用于生产环境时，请使用 add_host(..., use_ssl=true, winrm_port=5986, winrm_cert_validation="validate", ssh_host_key_policy="reject") 注册，并将防火墙限制为仅允许你的运维 IP 访问。
• NTLM 会通过 HTTP 5985 加密负载。 即使没有 TLS，默认的 winrm_auth="ntlm" 也会对消息正文加密。启用脚本有意不启用 Basic/AllowUnencrypted/TrustedHosts=*（0.1.1+）——NTLM 不需要这些设置，启用它们只会削弱计算机的安全性。
• 计算机上的机密信息仅临时存放。 user_create / service_create 会将新密码暂存到计算机上的管理员专用文件中（不会出现在进程命令行或 Event 4688 中）；cmdkey 会在运维人员的计算机上存储 RDP 密码。这些信息绝不会返回给模型，日志也会对已知机密信息进行脱敏。
• 最小权限。 使用 WINRDP_ENABLED_TOOLS / WINRDP_DISABLED_TOOLS 限制工具范围，并在客户端中保持启用破坏性操作确认。
• 使用会破坏 NTLM 的代理/VPN？ 轮换代理（例如 TUN 模式下的 Clash）会破坏面向连接的 NTLM——多阶段握手需要一条持久 TCP 连接，而代理无法保持该连接，因此即使密码正确，WinRM 身份验证也会失败（有效登录时仍会看到 InvalidCredentials）。请在代理中将计算机 IP 配置为 DIRECT，或启用无状态的 Basic 身份验证：rdp_bootstrap(enable_basic=True)（或 enable_winrm(basic=True)）会在计算机上启用 Basic + AllowUnencrypted，然后使用 add_host(..., winrm_auth="basic") 注册。通过 HTTP 使用 Basic 会以接近明文的形式发送密码，因此请在提供商防火墙上将 WinRM 的访问范围限制为你的运维 IP。
• 服务端确认（可选）。 设置 WINRDP_CONFIRM_DESTRUCTIVE=1，让服务端在运行任何破坏性工具之前，通过 MCP elicitation 要求你确认——为不会根据 destructiveHint 进行拦截的客户端提供一道安全保障。不支持 elicitation 的客户端会退回到客户端侧拦截。

完整的威胁模型、凭据保险库内部机制、日志脱敏、参数注入防护和加固清单：docs/SECURITY.md。

---

文档

文档	内容
docs/PREPARE-SERVER.md	将全新云/VDS/专用计算机从锁定状态配置为可管理状态：提供商防火墙、冷启动选项、RDP 加固、验证、规格选择。
docs/PRODUCTION.md	安全地大规模运行：安装选项、保险库、传输加固、允许/阻止列表、可观测性、可靠性、机群管理、后台服务设置、清单。
docs/SECURITY.md	威胁模型、信任边界、凭据处理、传输/MITM、启用 WinRM 脚本、参数注入防护、加固清单。
docs/TROUBLESHOOTING.md	针对实际遇到的故障模式，按症状 → 原因 → 修复进行说明（部署失败、连接中断、提权缓慢、Python/Node 安装、SSH banner、5986 证书、MCP 注册）。
docs/ARCHITECTURE.md	供贡献者参考的内部架构图：传输 → PowerShell 封送 → 部署 → 提权 → 上下文 → 保险库 → 工具 → 服务组装。
docs/TOOLS.md	全部 147 个工具的完整参考——签名、参数、默认值和安全类别。

---

架构

winrdp-mcp 是一个 FastMCP 服务：工具调用共享的 Context，从加密保管库中解析目标主机，将 PowerShell 正文交给缓存的 Transport（WinRM / SSH / Local / SMB+WMI），再将分隔的 JSON 编组返回 — 传输层之上的任何部分都无需了解命令是如何到达目标主机的。完整内部实现请参阅 docs/ARCHITECTURE.md。

---

致谢与许可证

本项目基于两个采用 MIT 许可证的项目构建，并谨致谢 — 详见 NOTICE：

• winremote-mcp — 为本项目的主机端工具界面、风险等级模型，以及可选的 deploy_ui_agent 交互式桌面路径提供基础。
• windows-admin-mcp — 为以 WinRM 为主 / SSH 为后备的管理方式提供基础。

winrdp-mcp 自身新增的功能：零配置配置流程、通过一次性计划任务实现真正的 UAC / 提权、按需暂存工具、加密的多主机清单，以及一流的 RDP 控制。

MIT — 详见 LICENSE 和 NOTICE。