WinCtl

WinCtl

Claude やその他の MCP クライアントから Windows デスクトップをフル活用
画面を確認し、実際のアプリケーション UI を読み取って操作し、ウィンドウや プロセスを管理し、ファイルを扱い、シェルコマンドを実行できます。これらすべてを、 監査ログ付きの段階的な権限モデルのもとで行います。

---

このコネクターが選ばれる理由

多くのデスクトップ自動化サーバーは、スクリーンショットと click(x, y) ツールをモデルに渡すだけなので、ウィンドウが移動した途端に使えなくなります。このサーバーは、 Windows の自動化を確実にする実際の仕組みを中心に設計されています。

• まず UI Automation を使います。 uia_snapshot はアプリケーションのアクセシビリティ ツリーを読み取るため、Claude は古くなり得る座標ではなく、*「保存ボタン」*を指定して操作できます。 uia_invoke と uia_set_value はコントロールを直接操作します。
• 座標は常に正確です。 このプロセスは UI API に触れる前に、モニターごとの DPI 認識を宣言し、ウィンドウの生の矩形（見えない約 7px のサイズ変更用境界線を含む）ではなく、 DWM のフレーム境界を報告します。これがないと、拡大縮小されたディスプレイではすべての座標が 知らないうちにずれてしまいます。200％表示の場合、GetWindowRect は実際の端が 2641px のところを 1351px と報告します。
• 入力が確実に届きます。 合成キー入力は間隔を空けて送信します。Unicode キーイベントをまとめて送ると、 アプリケーションが文字を取りこぼしたり、重複して入力したりするためです。200 文字を超えるテキストは クリップボード経由で貼り付け、処理後にクリップボードを元に戻します。
• ハンドルが誤動作を招きません。 ウィンドウ ID は外部から判別できない形式で、フィンガープリントによって識別されます。 Windows はウィンドウハンドルを再利用するため、古いハンドルが気づかないうちに別のアプリを指すと、 自動化が誤ったウィンドウを閉じる原因になります。
• 失敗を正直に伝えます。 window_focus は実際にフォアグラウンドが切り替わったかを検証し、 Windows が拒否した場合はその旨を伝えます。エラーには HRESULT だけでなく、次に何をすればよいかが説明されます。

要件

• Windows 10（1809 以降）または Windows 11
• Node.js 20 以降
• コンパイラーやビルドツールは不要です。すべてのネイティブ依存関係にはビルド済みバイナリが含まれています。

インストール

Claude Desktop（推奨）

最新リリースから winctl.mcpb をダウンロードし、ダブルクリックします。Claude Desktop がインストールし、 権限プロファイル、許可するフォルダー、確認設定を UI 上で設定できるようにします。

Claude Code

まずグローバルにインストールしてから、コマンドを登録します。

npm install -g @sitharaj88/winctl
claude mcp add winctl -- winctl

2 つ目のコマンドに --scope user を追加すると、現在のプロジェクトだけでなく、 すべてのプロジェクトで利用できるようになります。

ここでは npx -y @sitharaj88/winctl を使わないでください。 動作はしますが、WinCtl は ビルド済みのネイティブバイナリ（sharp、koffi）に依存しており、npx は起動のたびに再解決します。 グローバルインストールでは約 3 秒ですが、npx では約 18 秒かかります。MCP クライアントはそれよりずっと前に タイムアウトして、Connection closed を報告します。

任意の MCP クライアント（手動設定）

{
  "mcpServers": {
    "winctl": {
      "command": "winctl",
      "env": {
        "WINCTL_PROFILE": "standard"
      }
    }
  }
}

winctl が PATH にない場合は、エントリーポイントを直接指定します。Windows で npm をグローバルインストールすると、 %APPDATA%\npm\node_modules に配置されます。

{
  "mcpServers": {
    "winctl": {
      "command": "node",
      "args": ["C:\\Users\\<you>\\AppData\\Roaming\\npm\\node_modules\\@sitharaj88\\winctl\\dist\\index.js"]
    }
  }
}

Claude Desktop の設定ファイルは %APPDATA%\Claude\claude_desktop_config.json にあります。

権限ティア

すべてのツールは、必ずいずれか1つのティアに属します。無効なティアのツールは登録されないため、モデルから見えず、実行を試みられることも、説明の読み込みでコンテキストを消費することもありません。

ティア	許可される操作
observe	スクリーンショット、ウィンドウ／モニターの列挙、UI ツリー、システムおよびプロセス情報、ファイルの読み取り
interact	マウスとキーボードの入力、UI Automation の呼び出し、ウィンドウのフォーカス／移動／クローズ、クリップボードへの書き込み
filesystem	ファイルの作成、変更、移動、削除
manage	プロセスの起動と終了、サービスの制御
shell	任意の PowerShell および cmd の実行

プロファイルには、以下のティアがまとめられています。

プロファイル	ティア
readonly	observe
standard (デフォルト)	observe、interact、filesystem
full	5つすべて

# Pick a profile
WINCTL_PROFILE=readonly

# …or choose tiers explicitly
WINCTL_TIERS=observe,interact

設定

変数	デフォルト	用途
WINCTL_PROFILE	standard	readonly、standard、full のいずれか
WINCTL_TIERS	—	明示的なティアのリスト。プロファイルを上書きします
WINCTL_ALLOWED_PATHS	—	ファイルツールが操作できるフォルダーをセミコロンで区切ったリスト
WINCTL_DENIED_PATHS	—	操作を拒否する追加のフォルダー
WINCTL_CONFIRM_DESTRUCTIVE	true	破壊的な操作の前に確認する
WINCTL_AUDIT_LOG	%LOCALAPPDATA%\winctl\audit.jsonl	監査ログのパス
WINCTL_AUDIT_DISABLED	false	監査を無効にする
WINCTL_MAX_IMAGE_WIDTH	1600	スクリーンショットの縮小後の幅
WINCTL_COMMAND_TIMEOUT_MS	60000	シェル／PowerShell の制限時間

認識されないプロファイル名を指定すると、意図を推測して書き込みアクセスを許可してしまうのではなく、警告を stderr に出力して readonly にフェイルクローズします。

ツール

画面（5）

ツール	権限レベル	説明
screen_list_monitors	observe	位置、解像度、DPI スケールを含むディスプレイの一覧
screen_capture	observe	モニターまたは仮想デスクトップ全体のスクリーンショットを撮影
screen_capture_region	observe	矩形領域のスクリーンショットを撮影
screen_capture_window	observe	ウィンドウが重なっていても、そのウィンドウのスクリーンショットを撮影
screen_list_capturable_windows	observe	個別にキャプチャできるウィンドウの一覧

ウィンドウ（7）

ツール	権限レベル	説明
window_list	observe	安定した ID と境界情報を含む、表示中のトップレベルウィンドウ
window_get_active	observe	キーボードフォーカスがあるウィンドウ
window_get_desktop_info	observe	仮想デスクトップの境界情報とカーソル位置
window_focus	interact	ウィンドウを前面に表示してフォーカスし、確認を行う
window_set_state	interact	最小化、最大化、元に戻す、非表示、表示
window_move	interact	ウィンドウを移動およびサイズ変更（最初に最大化を解除）
window_close	interact	ウィンドウに閉じるよう要求

入力（7）

ツール	権限レベル	説明
input_move_mouse	interact	カーソルを移動
input_click	interact	クリック、右クリック、またはダブルクリック
input_drag	interact	2 点間を補間しながらドラッグ
input_scroll	interact	垂直または水平方向にスクロール
input_type	interact	Unicode テキストを入力。長い場合は貼り付け
input_press_keys	interact	ctrl+shift+escape などのキーの組み合わせ
input_key_hold	interact	キーを押したままにする、または離す

UI オートメーション（4）

ツール	権限レベル	説明
uia_snapshot	observe	アプリケーションのアクセシビリティツリーを読み取る
uia_find	observe	名前、ID、または種類でコントロールを検索
uia_invoke	interact	コントロールのクリック、切り替え、展開、選択、またはフォーカス
uia_set_value	interact	編集可能なコントロールのテキストを直接設定

システムとプロセス（8）

ツール	権限レベル	説明
system_info	observe	OS、CPU、メモリ、ディスク、ネットワーク、バッテリー、GPU
system_list_services	observe	状態とスタートアップの種類を含むサービスの一覧
system_list_installed_apps	observe	インストール済みアプリケーション
system_notify	interact	Windows のトースト通知
system_control_service	manage	サービスの開始、停止、または再起動
process_list	observe	CPU とメモリの使用状況を含むプロセス
process_start	manage	アプリケーションを起動、またはドキュメントを開く
process_kill	manage	プロセスを終了

ファイル、クリップボード、シェル（9）

ツール	権限レベル	説明
file_known_folders	observe	標準の Windows パスと現在のアクセス制限
file_list	observe	サイズとタイムスタンプを含むディレクトリ一覧
file_read	observe	テキストまたは base64 コンテンツを読み取る
file_search	observe	名前のパターンと内容でファイルを検索
file_write	filesystem	書き込み、追記、または作成
file_manage	filesystem	コピー、移動、削除、mkdir
clipboard_read	observe	クリップボードのテキストを読み取る
clipboard_write	interact	クリップボードのテキストを設定
shell_run	shell	PowerShell または cmd のコマンドを実行

ツールは合計 40 個です。 すべてのツールに title、readOnlyHint、destructiveHint のアノテーションが付いています。

例

「メモ帳を開いて、会議のメモを書き込み、Documents に保存してください。」

Claude は通常、次のように処理します。

1. process_start → メモ帳を起動
2. window_list → ウィンドウを見つけ、ウィンドウを所有するプロセス ID を取得
3. window_focus → キー入力が確実にそのウィンドウに送られるようにする
4. input_type → クリップボードを使ってメモを貼り付け
5. input_press_keys ctrl+s、続けてファイル名フィールドに uia_set_value を実行
6. screen_capture_window → 画面で結果を確認

安全性

• ティアによる制御が主な境界です。有効化されていないツールは公開されません。
• パスの包含チェックでは、確認前にシンボリックリンクを解決するため、許可されたフォルダー内のリンクから拒否されたフォルダーへアクセスすることはできません。System32、WinSxS、Boot、Startup フォルダーは、full を含むすべてのプロファイルで拒否されます。
• 破壊的な操作の前に、MCP エリシテーションを通じて確認を求めます。
• すべての呼び出しを JSONL 形式で記録する監査ログ。機密情報に見える引数は伏せ字にされます。PRIVACY.mdをご覧ください。
• シャットダウン時に修飾キーを解放するため、キーの組み合わせを入力中にクラッシュしても、Ctrl が押されたままになることはありません。
• 自身のプロセスや PID 0～4 の終了は拒否します。

スクリーンショットは画面に表示されているものをすべてキャプチャし、AI プロバイダーに送信します。機密情報を扱うマシンで画面キャプチャを有効にする前に、PRIVACY.mdをお読みください。

権限の昇格

Windows では、通常の権限で実行中のプロセスが、昇格されたプロセスが所有するウィンドウを自動操作したり、キャプチャしたり、入力を送信したりすることが UIPI によってブロックされます。管理者アプリケーションを操作するには、コネクターを昇格して実行してください。そうしない場合、これらの呼び出しは何もせずに終わるのではなく、明確な説明とともに失敗します。

プライバシーポリシー

WinCtl はすべてお使いのマシン上で動作します。バックエンド、テレメトリー、アナリティクスはなく、独自のネットワーク通信も行いません。作者がお客様やお使いのコンピューターに関する情報を受け取ることはありません。

• **アクセスする情報：**画面の内容、ウィンドウとアプリケーションの状態、システムとプロセスの情報、許可したフォルダー内のファイル、クリップボードです。これらにアクセスするのは、ツールが呼び出された場合に限られます。合成入力を生成しますが、実際のキーボードやマウスの操作を記録することはありません。
• **データの送信先：**接続先の AI クライアントのみで、それ以外には送信しません。ツールが返す情報はすべてその会話の一部となるため、接続先クライアントのプライバシーポリシーが適用されます。スクリーンショットは画面に表示されているものをすべて AI プロバイダーに送信するため、機密情報を扱うマシンで画面キャプチャを有効にする前によくご検討ください。
• **保存される情報：**ローカルの監査ログ %LOCALAPPDATA%\winctl\audit.jsonl のみです。ツール呼び出しごとに 1 行記録され、機密情報に見える引数は伏せ字にされます。アップロードされることはありません。WINCTL_AUDIT_DISABLED=1 で無効にするか、いつでもファイルを削除できます。
• **保持と共有：**マシン外に情報が保持されることも、第三者と共有されることもありません。
• **お問い合わせ先：**Sitharaj Seenivasan — [email protected]

ポリシー全文：PRIVACY.md

開発

git clone https://github.com/sitharaj88/winctl
cd winctl
npm install
npm run build

npm run smoke                 # self-test against the live desktop
node scripts/smoke.mjs --full # full MCP protocol suite, including UI Automation
npm run inspect               # MCP Inspector UI

scripts/verify-interactive.mjs はメモ帳をエンドツーエンドで操作します。アプリを起動してテキストを入力し、UI Automation を通じてテキストを検証した後、クリーンアップを行います。実際のマウスとキーボードを使用するため、マシンを使用中は実行しないでください。

アーキテクチャ

src/
  index.ts              stdio entry point (DPI awareness runs first)
  http.ts               streamable HTTP entry point, loopback-only by default
  config.ts             profiles, tiers, limits
  security/             tier definitions, path containment, audit log, errors
  native/
    ffi.ts              koffi bindings to user32/kernel32/dwmapi
    dpi.ts              per-monitor DPI awareness
    handles.ts          opaque, fingerprinted window ids
    windows.ts          enumeration, focus, move, state
    input.ts            SendInput mouse and keyboard
    screen.ts           capture and token-aware encoding
    powershell.ts       per-call PowerShell execution
    uia.ts              UI Automation bridge
  server/
    registry.ts         tier gate + confirmation + audit in one place
    createServer.ts     assembles tools, resources and prompts
  tools/                the 40 tool definitions

この先拡張する場合に知っておくとよい実装上の注意点が 2 つあります。

• **PowerShell は呼び出しごとに 1 つのプロセスを実行します。**長時間稼働するホストのほうがよさそうですが、-Command - は stdin のストリームが閉じるまで入力全体をバッファーに格納し、文ごとには実行しないため、結果を返しません。呼び出しごとにプロセスを起動する方式なら、スクリプトがハングしても後続の呼び出しに影響しません。コマンドは -EncodedCommand（base64 UTF-16LE）として渡すため、シェルのクォートに起因するインジェクションの不具合を防げます。
• 起動時に **INPUT 構造体のサイズを検証します。**レイアウトが一致しなくても例外は発生せず、マウスイベントが不正な座標に送信されてしまいます。

公開

npm run build && npm publish --access public   # npm
npx @anthropic-ai/mcpb pack                    # build the .mcpb bundle
mcp-publisher login github && mcp-publisher publish   # MCP registry

Claude Connectors Directory への掲載を希望する場合は、拡張機能フォームからデスクトップ拡張機能を申請してください。

作者

Sitharaj Seenivasan

• ウェブサイト — sitharaj.in
• GitHub — @sitharaj88
• LinkedIn — in/sitharaj08
• メール — [email protected]

問題や機能リクエストはgithub.com/sitharaj88/winctl/issuesまでお寄せください。

ライセンス

MIT © Sitharaj Seenivasan