desktop-control-mcp

Ein Windows-Desktop-Automatisierungsserver, der Maus-, Tastatur-, Bildschirmaufnahme- und KI-gestützte UI-Elementerkennung über zwei Schnittstellen bereitstellt:

• MCP-Server (mcp_server.py) — stdio-Transport, ausgelegt für die Verwendung mit Claude Code, Claude Desktop und anderen MCP-Clients

• HTTP-Server (server.py + app.py) — eine Flask-API unter http://localhost:7845, über ein Symbol in der Taskleiste ausführbar

Beide Schnittstellen nutzen dieselben zugrunde liegenden controller.py- (Windows-Automatisierung) und ui_parser.py- (Vision-Modelle) Dateien, sodass die Funktionen identisch sind.

Highlights

• KI-basiertes Klicken per Sicht — UI-Elemente werden mit Microsoft OmniParser v2 (YOLO-Symbolerkennung + Florence-2-Beschriftung + EasyOCR) erkannt, sodass Sie Schaltflächen/Felder nach Absicht ansteuern können, anstatt Pixelkoordinaten aus einem Screenshot zu erraten.

• DPI-bewusst — läuft als PROCESS_PER_MONITOR_DPI_AWARE, sodass Koordinaten unabhängig von der Windows-Anzeigeskalierung immer physischen Pixeln entsprechen.

• Cursor in Screenshots — Das echte Windows-Cursor-Bitmap wird über die Win32-GDI-API in jeden Screenshot eingefügt, sodass KI-Clients sehen können, wo sich die Maus befindet.

• Drei Screenshot-Modi — einzelnes komprimiertes JPEG, kommentierte Erkennungsansicht und zeitlich gestaffelte Serienaufnahme (zur Beobachtung von Animationen oder Ladezuständen).

• Intelligente Tastatursteuerung — separate Werkzeuge für wörtlichen Text, einzelne Tasten und Tastenkombinationen, sodass "ctrl+c" nie versehentlich als Text eingegeben wird.

Related MCP server: desktop-automation-mcp

Installation

Erfordert Windows und Python 3.10+.

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

Beim ersten Start werden die OmniParser-v2-Modellgewichte (~1 GB) von Hugging Face in den lokalen Cache heruntergeladen. Eine GPU wird automatisch verwendet, wenn ein CUDA-fähiges PyTorch installiert ist; andernfalls wird die CPU verwendet.

Ausführen

Als MCP-Server (stdio)

Fügen Sie einen Eintrag wie diesen zu Ihrer MCP-Client-Konfiguration hinzu (z. B. Claude Desktop / Claude Code):

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

Der Server startet sofort; Modelle werden in einem Hintergrundthread geladen, sodass der erste detect_ui_elements-Aufruf auf sie wartet, die übrigen Werkzeuge jedoch sofort verfügbar sind.

Als HTTP-Server mit Taskleistensymbol

python app.py

Ein Taskleistensymbol mit Start / Stopp / Beenden erscheint. Die Flask-API lauscht auf http://localhost:7845. Endpunktdetails finden Sie in API_DOCS.md.

MCP-Werkzeuge

Bildschirminformationen

Screenshots

Maus

Tastatur

Der verbindliche Klick-Workflow

Koordinaten sind über Bildschirmänderungen hinweg nicht stabil – jedes Menü, jeder Dialog, jedes Scrollen verschiebt Dinge. Der Server erzwingt diese Schleife:

1. ERKENNEN – detect_ui_elements gibt die aktuelle Elementtabelle zurück.

2. FINDEN – Gleichen Sie Ihr Ziel in der Spalte Label ab.

3. KLICKEN – click_mouse(x, y) mit den exakten Center-Koordinaten aus der Tabelle.

4. ÜBERPRÜFEN – take_screenshot, um zu bestätigen, dass der Klick angekommen ist.

5. WIEDERHERSTELLEN – Wenn der Klick danebenging, erneut erkennen (der Bildschirm hat sich möglicherweise geändert) und erneut versuchen.

Erraten Sie niemals Koordinaten aus einem rohen Screenshot. Die Elementtabelle aus detect_ui_elements ist die maßgebliche Quelle.

Beispiel-Elementtabelle

  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

Um die Suchschaltfläche zu klicken: click_mouse(x=674, y=200).

HTTP-API

Wenn als app.py ausgeführt, spiegelt der Flask-Server auf Port 7845 die MCP-Werkzeuge wider:

Vollständige Anfrage-/Antwortschemata finden Sie in API_DOCS.md.

Dateistruktur

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

Plattformhinweise

• Nur Windows. Die Cursor-Komposition, DPI-Erkennung und der Code für aktive Fenster verwenden direkt Win32-APIs.

• Nur primärer Monitor. Alle Koordinaten liegen im Pixelraum des primären Monitors.

• Die erste Erkennung ist langsam. Das Laden des OmniParser-Modells und die EasyOCR-Initialisierung können beim ersten Aufruf 30–60 Sekunden dauern. Nachfolgende Erkennungen sind schnell (unter einer Sekunde auf der GPU, einige Sekunden auf der CPU).