MCP Windows Desktop Automation

MCP Windows Desktop Automation

対話型 Windows x64 デスクトップ向けの、信頼できるオーナー専用 MCP サーバーです。バージョン 2 では、従来の 50 個の AutoIt ツールと 7 個のプロンプトを維持しながら、実際の PNG スクリーンショットを追加し、SDK 2.0.0 を通じて MCP 2026-07-28 をサポートしています。レガシーの 2025-11-25 クライアントには、明示的な互換性を提供します。

実行

Node.js 22 以降が必要です。このリポジトリまたはレビュー済みのリリース成果物をインストールしてから、インストールされたコマンドを実行します。

npm ci
npm run build
node dist/index.js --transport=stdio
# After installing the package:
mcp-windows-desktop-automation --transport=stdio

Stdio の標準出力には MCP JSON メッセージのみが出力されます。詳細な操作名を含む診断情報は、引数の値を含めずに標準エラー出力へ出力されます。標準入力を閉じると、サーバーとそのネイティブヘルパーが終了します。

ネイティブ操作には Windows x64 と、ログインユーザーの対話型デスクトップが必要です。列挙とプロトコル処理は Linux でも実行されますが、ネイティブ呼び出しは明示的なプラットフォームエラーを返します。ARM64、セッション 0 のサービス、ヘッドレスの Windows セッション、他のユーザーのセッション、およびサーバーの権限を超える昇格ウィンドウはサポートされていません。プロバイダーアカウントやモデルは関与しません。

トランスポートと所有権

デフォルトは Stdio です。HTTP を使用する場合は、次の値を設定します。

• MCP_AUTH_TOKEN：32 文字以上のランダムなオーナーベアラートークン。
• MCP_FILE_ROOTS：既存のローカルディレクトリを含む JSON 配列。例：["C:\\Users\\me\\Documents"]。
• オプションの MCP_ALLOWED_HOSTS：ポートを使用する場合はポートも含めた、正確な Host 値のカンマ区切りリスト。
• オプションの MCP_ALLOWED_ORIGINS：正確なオリジンのカンマ区切りリスト。

mcp-windows-desktop-automation --transport=streamable-http --port=3000 を起動します。エンドポイントは http://127.0.0.1:3000/mcp です。--host=ADDRESS を指定すると、デフォルトのループバックアドレスを明示的に変更できます。すべてのエンドポイントリクエストで認証が必要です。Host と Origin は完全一致で検証され、転送ヘッダーは信頼されません。また、制限の緩い CORS は有効になっていません。リモート環境にデプロイする場合は、信頼できる TLS リバースプロキシを使用してください。

1 つのプロセスにつきオーナーは 1 人で、デスクトップ、クリップボード、ネイティブオプション、直列コマンドキューを共有します。そのトークンを持つすべてのクライアントは、runAs に渡す認証情報やシャットダウンを含む、同じ広範な OS 権限を持ちます。オーナーごとに、別の Windows アカウント、セッション、プロセスをデプロイしてください。ファイルルートが制限するのはファイルリソースのみであり、自動化ツールは OS サンドボックスではありません。このプライベートなベアラーデプロイメントでは OAuth を実装しておらず、マルチテナント認可を提供すると主張するものでもありません。

HTTP は、現在の Streamable HTTP と、意図的にステートレスなレガシーリクエストをサポートします。現在のクライアントは、標準の MCP プロトコル、メソッド、名前に一致するヘッダーを送信する必要があります。過去の SSE セッションエンドポイントはありません。以前の --transport=websocket ブランチは機能しないプレースホルダーでした。現在は WebSocket をサポートしていると偽るのではなく、移行メッセージを表示して失敗します。

保持されるツールとプロンプト

グループ	ツール
マウス	mouseMove, mouseClick, mouseClickDrag, mouseDown, mouseUp, mouseGetPos, mouseGetCursor, mouseWheel
キーボードとクリップボード	send, clipGet, clipPut, autoItSetOption, opt, toolTip
ウィンドウ	winActivate, winActivateByHandle, winActive, winClose, winExists, winGetHandle, winGetPos, winGetText, winGetTitle, winMove, winSetState, winWait, winWaitActive, winWaitClose
コントロール	controlClick, controlClickByHandle, controlCommand, controlGetText, controlSetText, controlSend, controlFocus, controlGetHandle, controlGetPos, controlMove, controlShow, controlHide
プロセス	run, runWait, runAs, runAsWait, processExists, processClose, processSetPriority, processWait, processWaitClose, shutdown
スクリーンショット	takeScreenshot

プロンプト：findWindow, windowInfo, fillForm, submitForm, automateTask, monitorWindow, takeScreenshot。

既存の AutoIt 引数規約はそのままです。文字列と整数には明示的な上限が設けられています。待機タイムアウトは秒単位で、デフォルトは 10、範囲は 1～25 です。以前のプロセスタイムアウトの説明では、誤ってミリ秒と記載されていました。クリック回数の上限は 100 です。テキスト取得関数は固定長の UTF-16 バッファー（デフォルト／最大 65,536 コード単位）を使用します。バッファーのサイズが不足している場合は、無言で切り詰めたり、際限なく割り当てたりせず、エラーを報告します。

実際のスクリーンショットとファイルリソース

takeScreenshot は MCP の image/png コンテンツを返します。

• { "target": "fullscreen" }：仮想デスクトップ全体の表示ピクセル。
• { "target": "window", "windowTitle": "..." }：Win32 PrintWindow を使用した AutoIt のウィンドウ選択。
• { "target": "region", "x": 20, "y": 20, "width": 100, "height": 80 }：仮想デスクトップ内に完全に収まる矩形。

リソースとして screenshot://desktop と screenshot://window/{percent-encoded-title} を公開します。これらは、従来のテキストのみのスクリーンショット用プレースホルダーに代わるものです。キャプチャには同梱の静的な Windows PowerShell スクリプトを使用し、リクエストデータは JSON の標準入力から渡されます。キャプチャはディスクに保存されません。PNG は 3,200 万ピクセル、8 MiB に制限され、ヘルパーの期限は 15 秒です。PrintWindow の対応状況はアプリケーションによって異なります。保護されたウィンドウ、最小化されたウィンドウ、ハードウェアレンダリングされたウィンドウでは、キャプチャが拒否されたり、空白のピクセルが生成されたりする場合があります。キャプチャによってウィンドウがアクティブになることはありません。

file:/// URI は、設定済みの正規ルート内にあるローカルファイルまたはディレクトリ一覧を読み取ります。stdio では作業ディレクトリがデフォルトのルートになります。HTTP ではルートを明示的に指定する必要があります。ファイルは通常ファイルで、サイズは 1 MiB 以下である必要があり、base64 のバイナリリソースコンテンツとして返されます。ディレクトリでは最大 1,000 件の名前が返されます。ネットワークホストを含むファイル URI と、シンボリックリンクによるルート外へのアクセスは拒否されます。これは、元の無制限なファイルアクセスに意図的に置き換わるものです。

キャンセルとシャットダウン

所有するネイティブヘルパーが 1 つ、AutoIt DLL を MCP イベントループから分離します。キューに入れられるツール／リソースジョブは最大 16 件です。各デスクトップリクエストには 30 秒の合計期限があります。ネイティブオプションはヘルパーが停止するまで保持されます。キャンセル、タイムアウト、またはネイティブクラッシュが発生すると、そのヘルパーは中断されます。後続のリクエストではデフォルトオプションで新しいヘルパーが起動します。中断された変更操作は再実行されません。すでに適用されたデスクトップ上の変更は元に戻されず、run/runAs を通じて意図的に起動されたアプリケーションが自動的に終了されることもありません。

アクティブな stdio リクエストは、リクエスト ID が数値の 0 の場合も含めてキャンセルできます。ステートレスなレガシー HTTP では、アクティブなレスポンスを閉じると、そのリクエストがキャンセルされます。別個のレガシーキャンセル通知で別のリクエストを指定することはできません。サーバーを停止すると、ワーカーの再起動が禁止され、トランスポート接続が閉じられます。

開発とエビデンス

npm run check
npm run test:package
npm audit --omit=dev --audit-level=high

CI では Linux と Windows 上で Node 22 および 24 を実行します。Windows のジョブでは、固有の所有者に割り当てられた WinForms フィクスチャに対する実際の AutoIt 呼び出し、Unicode のコントロールとクリップボードの往復、範囲を制限したテキスト、スクリーンショットのピクセルチェック、キャンセル、およびヘルパーのクリーンアップが必要です。Linux のジョブでは、そのプラットフォーム固有のネイティブフィクスチャのみを明示的にスキップします。両方のプラットフォームで、実際の新旧ワイヤーメッセージ、非公開の HTTP 境界、重複するクライアント ID による同時実行、ファイルルートからの逸脱、インストール済みパッケージの実行ファイル、クリーンな標準出力、および EOF をテストします。

シャットダウン、runAs、または任意のアプリケーションを呼び出すテストはありません。ネイティブフィクスチャはクリップボードのテキストを復元し、所有するウィンドウのみを閉じます。Windows のデスクトップ動作は使い捨てのランナーで検証しますが、すべてのサードパーティ製デスクトップアプリケーションとの互換性は、そのアプリケーションのコントロールと権限に依存します。

SDK の移行は、公式の v2 ガイドおよび2026 年のプロトコルガイドに従います。ネイティブオートメーションでは node-autoit-koffi を使用し、同梱の AutoIt DLL を呼び出す際は範囲を制限します。スクリーンショットには、Microsoft の PrintWindow API と CopyFromScreen API を使用します。