win-mind

WinMind

AI がアクセシビリティツリーを通じてあらゆるアプリを認識し、操作できる Windows MCP サーバーです。スクリーンショットも、マウス操作も、ピクセル位置の推測も不要です。さらに、200 種類以上の Windows ネイティブツールを備えています。

多くのコンピューター操作エージェントは画面を見ます。スクリーンショットを撮り、何千もの画像トークンをモデルに送り、座標を推測してクリックし、またスクリーンショットを撮ります。WinMind は、Windows がすでに把握している情報を読み取ります。すべてのアプリは、ナレーターや NVDA などのスクリーンリーダーが使うアクセシビリティレイヤーである UI Automation に、ボタン、テキストボックス、リスト、テキストを公開します。WinMind はその情報をコンパクトな番号付きツリーに変換するため、AI は一度の呼び出しで内容を読み取り、次の呼び出しで操作できます。アプリがほかのウィンドウの背後にある場合も同様です。

WhatsApp  (WhatsApp.Root.exe, window)
├─ [6] banner
│  ├─ [7] button "Chats" (42) checked [toggle]
│  ├─ [8] button "Calls" (4) unchecked [toggle]
├─ [20] textbox "Search or start a new chat" [set_value]
├─ [21] tabs "chat-list-filters" (4)
│  ├─ [22] tab "All" selected [select]
│  ├─ [23] tab "Unread 42" [select]
├─ [26] grid "Chat list" (9)
│  ├─ [29] row "Alex Yesterday Photo" [click]
│  ├─ [30] row "Study Group 3 unread messages Yesterday" [click]
└─ [37] button "Send document" [click]

ui_act(ref=30) でそのチャットを開きます。ui_act(name="Play", title_contains="spotify") で音楽を再生します。スクリーンショットは撮影していません。

ほかとの違い

	スクリーンショット型エージェント	WinMind
モデルが受け取るもの	画像（1 枚あたり数千トークン）	実際の名前、状態、操作を含むテキストツリー
画面を見る速度	数秒（撮影＋ビジョンモデル）	アプリ全体で 0.1～0.3 秒（プロセス間呼び出し 1 回）
クリック	ピクセル座標を使い、マウスを動かす	アプリ独自のアクセシビリティ操作。マウスは動きません
ほかのウィンドウの背後にあるアプリ	前面に移動する必要がある	バックグラウンドで読み取り、操作できます
エディターやドキュメント内のテキスト	OCR	アプリから取得する正確なテキスト（TextPattern）

WinMind は、単純な UI Automation ツールではうまく扱えない次のようなケースにも対応します（詳しくはdocs/ARCHITECTURE.mdをご覧ください）。

• ほかのウィンドウの背後にある Chromium ベースのアプリ（Discord、Spotify、Steam、Teams、VS Code）では、ウィンドウに覆われると Chromium のオクルージョントラッキングが一時停止するため、コンテンツが公開されません。WinMind は一度適切に再開させると、その後はバックグラウンドでもツリーを読み取れる状態に保ちます。全画面ゲームの前面にウィンドウを移動することはありません。
• WebView2 をホストする WinUI 3 アプリ（WhatsApp）では、アプリ自身の Web コンテンツを再帰的に読み込むため、単純なスキャンでは同じ要素を何千回も取得してしまいます。WinMind は分割と重複排除を行い、7.3 秒から 0.25 秒に短縮します。
• Web のクリックが何も起こさずに失敗するケース：クリックハンドラーが内側のリンクにあるリスト項目を押す場合です。WinMind はマウスを動かさずに、実際にクリックを受け持つ要素の既定のアクションを実行します。
• 1 つのツリーにボタンとテキストの両方を表示：エディターやドキュメントの内容も、コントロールと並べて取得できます。
• タイトルだけでなくプロセスからアプリを検出（Spotify のタイトルは再生中の曲名です）。システムトレイに隠れたアプリも検出します。
• トークン予算：222 個のツール定義に必要なトークンは約 32k（ツール 1 個あたり 143 トークン）です。長い出力は切り詰めた箇所を示す注記付きで短縮し、エラーはトレースバックではなく、対処方法がわかる 1 行で示します。

内容一覧（222 個のツール）

分野	例
UI 自動化	ui_tree、ui_map、ui_act、ui_read、ui_find_text、ui_element_at、ui_focused
健康状態と診断	full_health_scan、why_is_my_pc_slow、smart_disk_health、battery_health、reliability_records
ハードウェアとゲーム	CPU/GPU のメトリクス、温度、ファン、FPS／フレーム時間／カクつき／GPU ボトルネック（PresentMon）
OS のライブトレース	ETW のプロセス／DNS／ファイル／ネットワークイベント
ネットワーク	why_no_internet、port_process_map、whats_on_port、DNS キャッシュ、Wi-Fi スキャン
プライバシーとセキュリティ	whats_using_my_webcam／_mic、Defender、BitLocker、USB 履歴、スタートアップ項目
Windows とデスクトップ	ウィンドウ、仮想デスクトップ、保存済みワークスペース
ファイル、プロセス、サービス、レジストリ	システムフォルダー、重要なキー、OS の中核プロセスに対する保護機能付き
ディスプレイ、オーディオ、メディア、音声	アプリごとの音量、再生中のメディア＋メディア操作、明るさ、夜間モード、TTS
画面キャプチャ（明示的な操作のみ）	capture_window_image は、ほかのウィンドウに覆われていても単一のウィンドウを描画します

ツールごとに1行で記載した全一覧は、TOOLS.md をご覧ください。AI は tool_guide を呼び出して、カテゴリ別の索引を確認することもできます。

クイックスタート

ワンクリック：Claude Desktop

Releases から winmind-mcp-<version>.mcpb をダウンロードして開くと、Claude Desktop がブラウザー拡張機能と同様にインストールします（uv が必要です。Python の依存関係は uv がセットアップします）。バンドルにはネイティブヘルパーが含まれています。

すべての MCP クライアント（Claude Code、Cursor、VS Code、ローカルモデルなど）

必要な環境：Windows 10/11、Python 3.10 以降。

git clone https://github.com/jhonpork1233-beep/win-mind
cd win-mind
pip install -e .

MCP クライアントに追加します。PATH が変更されても問題が起きないよう、Python の絶対パスを指定してください。

// Claude Desktop / Claude Code (~/.claude.json "mcpServers") / any MCP client
{
  "winmind": {
    "command": "C:\\Path\\To\\Python\\python.exe",
    "args": ["-m", "winmind"]
  }
}

Claude Code でのショートカット：claude mcp add winmind -- "C:\Path\To\Python\python.exe" -m winmind

次のように質問してみてください。「WhatsApp の未読チャットには何がある？」、「Spotify でお気に入りの曲を再生して」、「PC の動作が遅いのはなぜ？」、「ウィンドウを切り替えずにメモ帳のスクリーンショットを撮って」

任意のネイティブヘルパー

コア機能（UI エンジン、ファイル、プロセス、レジストリ、健康状態、ネットワークなど）は純粋な Python で動作します。一部のツールでは、ライブイベントフック、ETW、ウィンドウストリーミング、仮想デスクトップ、WinRT ブローカー（メディア、通知）、HUD オーバーレイ、PresentMon などの小さなネイティブヘルパーを使用します。native/ でソースからビルドしてください。

powershell -ExecutionPolicy Bypass -File scripts\build_all.ps1

（Visual Studio 2022 Build Tools の C++ ワークロードと Windows SDK が必要です。また、winmind_native.dll には MinGW の g++ が必要です。）ヘルパーがビルドされていないツールはその旨を表示し、実行するスクリプトを知らせます。

効率的な使い方（AI クライアントとプロンプト作成者向け）

• まず ui_tree（構造）または ui_read（テキストのみ）を使います。スクリーンショットは使いません。
• 名前が明確な場合は名前で操作します：ui_act(name="Search", title_contains="spotify")。それ以外の場合は ref を使います。
• 生の一覧（appx_packages、service_list、port_process_map）より、要約ツール（full_health_scan、system_health_summary、windows_summary）を優先してください。
• すべてのツールは detail=true（省略なし）、compact=true（短いキー）を受け付けます。
• ツールの遅延読み込みに対応するクライアント（Claude Code のツール検索など）は、使用する定義だけを読み込みます。

安全性

WinMind はユーザーの権限で実行され、システムを変更できます。それがこのツールの目的です。SECURITY.md をお読みください。

• すべてのツールには MCP のリスク注釈（readOnlyHint、destructiveHint）が付いているため、クライアントはリスクの高い呼び出しの前に確認できます。16 個のツールに破壊的操作のマークが付いています。
• 組み込みの保護機能：ファイルツールは Windows/System32/Program Files とドライブのルートを拒否し、レジストリの書き込み／削除ツールは重要なキーを拒否し、プロセスツールは OS の中核プロセスを拒否します。
• UI エンジンはスクリーンショットを撮影せず、マウスも動かしません。画面キャプチャは明示的に呼び出すツールでのみ行えます。
• テレメトリーはありません。WinMind が書き込むすべてのデータは %LOCALAPPDATA%\WinMind に保存されます（WINMIND_HOME で変更できます）。
• 管理者専用のツールが必要な場合を除き、昇格されていない権限で実行してください。

テスト

pip install -e .[dev]
python tests\audit_tools.py tests\audit.json     # calls every safe tool, sandbox-tests the write tools
python tests\audit_summary.py tests\audit.json

監査で書き込みが行われるのは、一時フォルダー、使い捨てのレジストリキー HKCU\Software\WinMindAudit、監査自身が起動したプロセス、および監査専用のメモ帳ウィンドウだけです。現在の結果：読み取り専用ツールは 102/109 件が正常です（残りは管理者権限、実行中のセッション、または開いている Office ドキュメントが必要です）。サンドボックスとガードのテストは 37/37 件が合格しています。

ロードマップ

• Java Access Bridge（Java／Swing アプリ）、Firefox／LibreOffice 用 IAccessible2 テキスト
• 安定したセレクターと記録済みワークフロー
• ライブ UI イベントストリーム（再読み込みの代わりにツリー差分を使用）
• さらに高速なツリー取得を実現する UI Automation Remote Operations
• ワンクリックインストール：Claude Desktop 拡張機能、Windows エージェントコネクター（On-Device Registry）
• 他の Windows MCP サーバーとの公開直接比較ベンチマーク

ライセンス

Apache-2.0。サードパーティコンポーネント：THIRD_PARTY_NOTICES.md。