winrdp-mcp

winrdp-mcp

Claude と Claude Code 向けに、あらゆる Windows RDP マシン（Windows 10/11 および Server 2016–2025）をプロビジョニングし、完全に管理するゼロ設定の MCP サーバーです。

ホストと管理者の認証情報を渡すだけで、マシンを単独でリモート管理できる状態にします。初期状態や Windows のバージョンを問わず、WinRM を有効にし、Windows ファイアウォールを開き、ローカル管理者のトークンフィルタリングを修正します。Claude はその後、シェル、ファイル、レジストリ、サービス、プロセス、スケジュールタスク、ユーザー、ファイアウォール、イベントログ、ソフトウェア、ネットワーク、ライブ RDP 制御、スクリーンショット、GUI オートメーション、実際の UAC 昇格、ワンコールのヘルス／セキュリティレポート、オンデマンドのツール配置など、147 個のツールを利用できます。さらに、6 つのガイド付きワークフロー（プロンプト）とライブホストリソースも備えています。

ターゲットには何も事前インストールする必要はありません。 コントローラーは Claude Code の実行場所を問わず、WinRM／SSH／SMB 経由でマシンに接続し、単一のサーバーから 1 台または複数台のマシンを管理します。

違い

• ゼロ設定のプロビジョニング。 provision_host は WinRM → SSH → SMB/WMI によるコールドスタート → 1 回限りの貼り付けによるブートストラップの順に試し、新しくロックダウンされたマシンを、手動で WinRM を設定することなく管理可能にします。
• 「管理者として実行してください」ではなく、実際の UAC／昇格。 WinRM 経由では、ローカル管理者は高整合性の完全なトークンを取得し、昇格操作を直接実行します。トークンがフィルタリングされている場合は、1 回限りの 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、バッチでも同様です。stage_tool を使えば、タスクの途中で Sysinternals（または任意の URL／ローカルファイル）をマシンに取得できます。
• ネイティブ GUI オートメーション。 オンボックスのエージェントなしで、インタラクティブな RDP デスクトップのキー入力、マウス、UI オートメーション（名前でコントロールを検索／クリック／読み取り）を操作し、ライブスクリーンショットも取得できます。
• ワンコール運用。 health_report（OS／CPU／RAM／ディスク／サービス／エラー／更新／Defender を 1 回で読み取り）、apply_baseline（高パフォーマンス電源プラン、スリープ無効、長いパスへの対応）、whoami_priv、failed_logons、list_open_ports。
• 本格的な RDP 対応と、タグおよびフリート全体への並列処理を備えた暗号化された複数ホストのインベントリ（Fernet）。

2 つのモード、1 つのパッケージ

モード	コマンド	実行場所	マシンへの接続方法
コントローラー（デフォルト）	winrdp-mcp serve	Claude Code の実行場所	WinRM／SSH／SMB+DCOM
エージェント	winrdp-mcp agent	マシン上	ローカル PowerShell

どちらも同じサーバーを構築します。python -m winrdp_mcp serve はコンソールスクリプトと同等です。

---

目次

1. クイックスタート
2. ツールグループ
3. ボックスの準備
4. 主な機能
5. 設定
6. セキュリティ
7. ドキュメント
8. アーキテクチャ
9. クレジットとライセンス

---

クイックスタート

1. インストール

オペレーターのマシン（Windows、macOS、または Linux）に Python 3.10+ が必要です。対象は 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" }
    }
  }
}

または、CLI から登録します。

claude mcp add winrdp -- winrdp-mcp serve

保存された認証情報を保存時に暗号化するため、WINRDP_VAULT_KEY に強力なパスフレーズを設定してください（設定を参照）。全 147 個ではなく、目的に応じたツールセットを公開するには、WINRDP_PROFILE に admin、rdp、または core を設定します。

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 は RDP セッションに一度だけ貼り付ける bootstrap_oneliner を返します。または、rdp_bootstrap を呼び出すと、そのコマンドがクリップボードにコピーされて mstsc が開くため、一度貼り付けるだけで済みます。ボックスの準備を参照してください。

---

ツールグループ

15 個のモジュールにまたがる 147 個のツール。すべてのシグネチャ、パラメーター、デフォルト値、安全性クラスを含む完全なカタログは、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、zip／unzip、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 オートメーション（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 — 1 回の呼び出しでヘルスとセキュリティ情報を取得します

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	1 台のマシンの簡潔なリアルタイム概要（OS、ビルド、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(...) を呼び出します。すべての機能に引き続きアクセスでき、削除される機能はありません。

---

マシンの準備

コントローラーは、管理用トランスポートを 1 つ使って対象に接続できる必要があります。最も望ましいのは（WinRM がすでに有効な場合）、provision_host がすべてを実行する方法です。新しく用意したクラウドマシンで手動操作が必要になる可能性があるのは、次の 2 つだけです。

1. プロバイダーのファイアウォール／セキュリティグループで、管理用の受信ポートを 1 つ開く（WinRM-HTTP の場合は 5985、HTTPS の場合は 5986）。これは Windows の外部で行う必要があり、winrdp-mcp では設定できません。
2. トランスポートを 1 つ有効にする。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／昇格されていないローカル実行）の場合は、1 回限りの SYSTEM スケジュールタスクにフォールバックします。as_user=True は表示中のデスクトップセッション内で実行します。GUI、クリップボード、スクリーンショットにはこれが必要です。

任意のスクリプトを 1 回の呼び出しで実行

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 を検出するか、バックグラウンドでインストールします（winget → choco → python.org）。グロブを使って実際の 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 は、1 つのスクリプトを複数のマシンで並行実行し（デフォルトの 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 の場合、stderr に詳細な 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 で算出されます）。

ログはstderr のみに出力されます。stdio トランスポートでは stdout が 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 経由のペイロードを暗号化します。 デフォルトの winrm_auth="ntlm" は、TLS を使用しなくてもメッセージ本文を暗号化します。有効化スクリプトでは、意図的に Basic／AllowUnencrypted／TrustedHosts=* を有効にしません（0.1.1+）。NTLM にこれらは不要であり、有効にしてもマシンのセキュリティを弱めるだけだからです。
• マシン上のシークレットは一時的なものです。 user_create／service_create は、新しいパスワードを管理者のみが読み取れるファイルに一時保存します（マシン上で読み取られ、プロセスのコマンドライン／イベント 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 バナー、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 ライセンスの 2 つのプロジェクトを基盤として構築し、謝辞を表します。詳しくは NOTICE をご覧ください。

• winremote-mcp — マシン上のツール群、リスク階層モデル、オプションの deploy_ui_agent インタラクティブデスクトップ経路の基盤です。
• windows-admin-mcp — WinRM を優先し、SSH をフォールバックとする管理方式の基盤です。

winrdp-mcp 独自の追加機能：ゼロ設定のプロビジョニング手順、一回限りのスケジュールタスクによる実際の UAC／昇格、オンデマンドのツールステージング、暗号化されたマルチホストインベントリ、そして本格的な RDP 制御です。

MIT — LICENSE と NOTICE をご覧ください。