desktop-control-mcp
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ツール
画面情報
ツール | 説明 |
| プライマリモニターの解像度。座標空間を把握するために一度呼び出します。 |
| 現在フォーカスされているウィンドウのタイトル、位置、サイズ。 |
スクリーンショット
ツール | 説明 |
| プライマリモニターの圧縮JPEG。観察専用 のため、座標を導出しないでください。 |
| OmniParser + EasyOCRを実行し、注釈付き画像と、検出された各要素の |
| 指定された時間にわたってNフレームを均等にキャプチャします。アニメーション、ローディングスピナー、タイミングに敏感なUIに便利です。 |
マウス
ツール | 説明 |
| シングルクリック。常に |
| ダブルクリック。 |
| クリックせずにカーソルを移動。 |
| クリック&ドラッグ。 |
| 位置でホイールスクロール( |
キーボード
ツール | 使用する場面 |
| プレーンテキスト入力(ファイル名、検索クエリ、URL、コード)。 |
| 単一の名前付きキー( |
| 修飾キー+キーコンボのみ( |
必須のクリックワークフロー
座標は画面の変化に対して安定していません。メニューが開くたび、ダイアログが表示されるたび、スクロールするたびに位置が変わります。サーバーはこのループを強制します:
検出 —
detect_ui_elementsが現在の要素テーブルを返します。検索 —
Label列でターゲットを照合します。クリック — テーブルの正確な
Center座標を使用してclick_mouse(x, y)を実行します。検証 —
take_screenshotでクリックが成功したか確認します。回復 — クリックが外れた場合は、再検出(画面が変わっている可能性があります)して再試行します。
生のスクリーンショットから座標を推測しないでください。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ツールをミラーリングします:
エンドポイント | 目的 |
| 生存確認。 |
| 画面のbase64 PNGを返します。 |
|
|
|
|
|
|
|
|
| ブラケットコマンドのリストを、オプションの |
完全なリクエスト/レスポンススキーマは 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
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
MCP server for building and testing AI agents with multi-model experimentation and insights.
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceMCP server that provides computer control capabilities including mouse movements, keyboard actions, screenshot capture with OCR, and window management through a unified API.549 PyPI176MIT
- AlicenseNot gradedqualityDmaintenanceWindows desktop automation MCP server supporting mouse, keyboard, screenshot, and image recognition, with native CJK text input via clipboard.MIT
- AlicenseNot gradedqualityDmaintenanceMCP 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 npm3MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for Windows desktop automation, enabling agents to control mouse, keyboard, and UI elements via 22 tools, with OCR, screenshots, macro recording, and autonomous mission execution.MIT