Skip to main content
Glama
desktop-control-mcp

desktop-control-mcp

desktop-control-mcp

Claude Desktop Controller 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ツール

画面情報

ツール

説明

get_screen_size()

プライマリモニターの解像度。座標空間を把握するために一度呼び出します。

get_active_window()

現在フォーカスされているウィンドウのタイトル、位置、サイズ。

スクリーンショット

ツール

説明

take_screenshot(quality=30)

プライマリモニターの圧縮JPEG。観察専用 のため、座標を導出しないでください。

検出 detect_ui_elements(confidence_threshold=0.5, full_response=True)

OmniParser + EasyOCRを実行し、注釈付き画像と、検出された各要素の (id, type, confidence, center, label) のテーブルを返します。これがクリック座標を見つける方法です。

take_screenshot_burst(frame_count=1.0, duration_seconds=1.0)

指定された時間にわたってNフレームを均等にキャプチャします。アニメーション、ローディングスピナー、タイミングに敏感なUIに便利です。

マウス

ツール

説明

click_mouse(x, y, button="left")

シングルクリック。常に detect_ui_elements の座標を使用してください。

double_click(x, y)

ダブルクリック。

move_mouse(x, y)

クリックせずにカーソルを移動。

drag_mouse(x1, y1, x2, y2, button="left")

クリック&ドラッグ。

scroll(x, y, direction, amount=1.0)

位置でホイールスクロール(up/down/left/right)。

キーボード

ツール

使用する場面

type_text(text)

プレーンテキスト入力(ファイル名、検索クエリ、URL、コード)。+ をホットキーとして解釈しません。

press_key(key, presses=1.0)

単一の名前付きキー(enter、tab、escape、f5、矢印キー、delete など)。

send_keys(text)

修飾キー+キーコンボのみ(ctrl+c、alt+tab、win+d、ctrl+shift+s)。


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

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

  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ツールをミラーリングします:

エンドポイント

目的

GET /health

生存確認。

POST /screenshot

画面のbase64 PNGを返します。

POST /move

{x, y} — カーソルを移動。

POST /click

{x, y, button?} — クリック。

POST /keys

{keys} — テキストまたはホットキー(自動検出)。

POST /command

[ClickMouse(500,300)] のような単一のブラケットコマンド。

POST /actions

ブラケットコマンドのリストを、オプションの delay を挟んで順次実行します。

完全なリクエスト/レスポンススキーマは 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では数秒)。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server that provides computer control capabilities including mouse movements, keyboard actions, screenshot capture with OCR, and window management through a unified API.
      549 PyPI
      176
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for driving any Windows app through five layers including OCR, UI Automation, and direct OS operations. Enables AI agents to control Windows desktop and OS cursor-free, even on background/locked windows.
      122 npm
      3
      MIT