desktop-control-mcp

Windowsデスクトップ自動化サーバーで、マウス、キーボード、画面キャプチャ、AIによるUI要素検出を2つのインターフェースで提供します：

• MCPサーバー (mcp_server.py) — stdioトランスポート。Claude Code、Claude Desktop、その他のMCPクライアントでの使用を想定

• HTTPサーバー (server.py + app.py) — http://localhost:7845 で動作するFlask API。システムトレイアイコンから起動可能

両インターフェースは同じ基盤の controller.py（Windows自動化）と ui_parser.py（ビジョンモデル）を共有しているため、機能は同一です。

ハイライト

• AIビジョンによるクリック — UI要素は Microsoft OmniParser v2（YOLOアイコン検出器 + Florence-2キャプショナー + EasyOCR）で検出されるため、スクリーンショットからピクセル座標を推測するのではなく、意図に基づいてボタンやフィールドを指定できます。

• DPI対応 — PROCESS_PER_MONITOR_DPI_AWARE として実行されるため、Windowsの表示スケーリングに関係なく、座標は常に物理ピクセルです。

• スクリーンショット内のカーソル — 実際のWindowsカーソルビットマップがWin32 GDI APIを介してすべてのスクリーンショットに合成されるため、AIクライアントはマウスの位置を確認できます。

• 3つのスクリーンショットモード — 単一の圧縮JPEG、注釈付き検出ビュー、時間分散バーストキャプチャ（アニメーションやローディング状態の観察用）。

• スマートなキーボードディスパッチ — リテラルテキスト、単一キー、修飾キーコンボ用の個別ツールにより、"ctrl+c" が誤ってテキストとして入力されることはありません。

Related MCP server: desktop-automation-mcp

インストール

WindowsとPython 3.10+が必要です。

git clone https://github.com/ahmetdenizyilmaz/desktop-control-mcp.git
cd desktop-control-mcp
pip install -r requirements.txt

初回実行時、OmniParser v2モデルの重み（約1GB）がHugging Faceからローカルキャッシュにダウンロードされます。CUDA対応のPyTorchがインストールされている場合はGPUが自動的に使用され、それ以外の場合はCPUが使用されます。

実行

MCPサーバーとして（stdio）

MCPクライアント設定（例：Claude Desktop / Claude Code）に次のようなエントリを追加します：

{
  "mcpServers": {
    "desktop-control": {
      "command": "python",
      "args": ["C:\\path\\to\\desktop-control-mcp\\mcp_server.py"]
    }
  }
}

サーバーは即座に起動します。モデルはバックグラウンドスレッドで読み込まれるため、最初の detect_ui_elements 呼び出しはモデルの読み込みを待ちますが、他のツールはすぐに利用可能です。

トレイアイコン付きHTTPサーバーとして

python app.py

トレイアイコンが表示され、Start / Stop / Quit が操作できます。Flask APIは http://localhost:7845 で待ち受けます。エンドポイントの詳細は API_DOCS.md を参照してください。

MCPツール

画面情報

スクリーンショット

マウス

キーボード

必須のクリックワークフロー

座標は画面の変化に対して安定していません。メニューが開くたび、ダイアログが表示されるたび、スクロールするたびに位置が変わります。サーバーはこのループを強制します：

1. 検出 — detect_ui_elements が現在の要素テーブルを返します。

2. 検索 — Label 列でターゲットを照合します。

3. クリック — テーブルの正確な Center 座標を使用して click_mouse(x, y) を実行します。

4. 検証 — take_screenshot でクリックが成功したか確認します。

5. 回復 — クリックが外れた場合は、再検出（画面が変わっている可能性があります）して再試行します。

生のスクリーンショットから座標を推測しないでください。detect_ui_elements の要素テーブルが唯一の情報源です。

要素テーブルの例

  ID  Type   Conf   Center         Label
   1  text   0.98   ( 499,   55)   File  Edit  View
   2  icon   0.91   ( 674,  200)   Search button
   3  icon   0.87   (1200,  400)   Close

検索ボタンをクリックするには：click_mouse(x=674, y=200)。

HTTP API

app.py として実行すると、ポート 7845 のFlaskサーバーがMCPツールをミラーリングします：

完全なリクエスト/レスポンススキーマは API_DOCS.md にあります。

ファイル構成

mcp_server.py          FastMCP server — tool definitions and lifespan
controller.py          Win32 / pyautogui / mss core — screenshots, input, window info
ui_parser.py           OmniParser v2 loading + UI detection + image annotation
screenshot_manager.py  Disk-side screenshot cache (cleanup, naming, burst dirs)
overlay.py             On-screen overlay utilities
lock_manager.py        Concurrency lock for shared resources
server.py              Flask HTTP API
app.py                 Tray-icon launcher for the Flask server
templates/index.html   Web UI for the Flask server
requirements.txt       Python dependencies
API_DOCS.md            HTTP endpoint reference
run_agents.bat         Convenience launcher for Claude Code in this folder

プラットフォームに関する注意

• Windowsのみ。 カーソル合成、DPI認識、アクティブウィンドウのコードはWin32 APIを直接使用します。

• プライマリモニターのみ。 すべての座標はプライマリモニターのピクセル空間にあります。

• 最初の検出は遅い。 OmniParserモデルの読み込みとEasyOCRの初期化には、最初の呼び出しで30〜60秒かかることがあります。以降の検出は高速です（GPUではサブ秒、CPUでは数秒）。