🍏 macOS Computer Use (MCP Server)

Ein ultraschneller, nativer Model Context Protocol (MCP)-Server, der LLMs und autonomen Agenten visuelle Inspektion und Fail-Closed-Desktop-Automatisierung auf macOS bietet.

Gebaut mit einem kompilierten Swift-Kern, der Apples native CoreGraphics, Vision OCR (VNRecognizeTextRequest) und Accessibility-APIs für semantische Hintergrundaktionen nutzt. Ungezielte Eingaben bleiben ein expliziter globaler CoreGraphics-Fallback.

⚡ Wichtige Highlights

• 🎯 Native Apple Vision OCR (find_text / click_text): Findet sichtbaren Text mit explizitem exact-, word-, prefix- oder substring-Abgleich und verweigert mehrdeutige Klicks, sofern kein Vorkommen ausgewählt wird.

• 🛡️ Fail-Closed-Targeting: windowId ist maßgeblich. Ungültige IDs und App/Fenster-Konflikte geben Fehler zurück, anstatt auf ein anderes Fenster oder den gesamten Bildschirm zurückzufallen.

• 🔐 Standardmäßig sicher: Globale Zeiger-/Tastatureingaben, Aktivierung der Vordergrund-App und benutzerdefiniertes AppleScript sind deaktiviert, es sei denn, der MCP-Prozess startet mit MACOS_COMPUTER_USE_UNSAFE=1.

• 🩺 Berechtigungs-Preflight: get_capabilities meldet die Bereitschaft von Accessibility, Bildschirmaufnahme und Ereignissynthese, ohne die macOS-Berechtigungsanfrage-APIs aufzurufen.

• ♿ Hintergrund-Accessibility-Aktionen: Steuerelemente inspizieren, Werte setzen, semantische Aktionen ausführen und bearbeitbare Steuerelemente anvisieren, ohne deren Anwendung zu aktivieren.

• ⏱️ Semantisches Warten im Hintergrund: Wartet auf das Erscheinen von Accessibility-Steuerelementen, ohne einen Screenshot zu machen oder Bildschirmaufnahme zu benötigen.

• 🖱️ Live-Agent-Cursor: Klicks und Scrollen gleiten einen markanten, klickdurchlässigen Cursor-Overlay zum Ziel, zeigen Erfolgs- oder Fehlerfeedback und blenden bei Inaktivität aus, ohne den physischen Zeiger zu bewegen.

• 👁️ Passender Screenshot-Cursor (mark_cursor): Zurückgegebene Aktions-Screenshots rendern denselben Agent-Cursor an der Zielkoordinate.

• ⚡ Reaktive UI-Synchronisierung (wait_for_text): Ersetzt blinde sleep()-Timeouts durch eine Hochgeschwindigkeits-OCR-Polling-Schleife, die auflöst, sobald dynamische Autocomplete-Dropdowns, Modals oder Zustandsänderungen erscheinen.

• 🖼️ Fensterisolierte Bildschirmaufnahme: Erfasst Zielanwendungs-Puffer sauber im Hintergrund (screencapture -l <wid> -o -x), ohne das Fenster in den Vordergrund zu bringen oder überlappende Fenster zu erfassen.

Related MCP server: ScreenHand

🛠️ Verfügbare Tools

🚀 Installation & Einrichtung

Mit npx ausführen

Konfigurieren Sie einen MCP-Client, um das neueste öffentliche Paket herunterzuladen, zu bauen und zu starten:

{
  "mcpServers": {
    "macos-computer-use": {
      "command": "npx",
      "args": ["-y", "macos-computer-use-mcp"]
    }
  }
}

Das Paket enthält einen ad-hoc-signierten universellen Swift-Helfer für Apple Silicon und Intel-Macs, sodass npx keinen lokalen Swift-Compiler oder eine Installationsskript-Genehmigung benötigt.

Die Standardkonfiguration stellt semantische Hintergrundautomatisierung und schreibgeschützte Inspektion bereit. Für Workflows, die absichtlich globale Zeiger-/Tastatureingaben, Vordergrundaktivierung oder beliebiges AppleScript benötigen, aktivieren Sie dies explizit:

{
  "mcpServers": {
    "macos-computer-use": {
      "command": "npx",
      "args": ["-y", "macos-computer-use-mcp"],
      "env": {
        "MACOS_COMPUTER_USE_UNSAFE": "1"
      }
    }
  }
}

1. Voraussetzungen

• macOS 13.0+ (Apple Silicon oder Intel)

• Node.js 20+

• Xcode Command Line Tools nur beim Bauen aus dem Quellcode:

  xcode-select --install

2. Klonen & Bauen

git clone https://github.com/johnexzy/macos-computer-use.git
cd macos-computer-use
npm install
npm run build

🔒 Fähigkeitsbasierte macOS-Berechtigungen

Gewähren Sie nur die Berechtigung, die für die von Ihnen verwendeten Tools benötigt wird. macOS weist die Berechtigung der Host-Anwendung zu, die den MCP-Server ausführt (Terminal, OpenCode, Cursor, VS Code usw.):

1. Accessibility: Erforderlich für semantische Inspektion und Aktionen. Es erfordert keine Bildschirmaufnahme.

2. Bildschirm- und Systemaudio-Aufnahme: Nur erforderlich für Screenshots und Vision-OCR-Tools wie screenshot, find_text, click_text und wait_for_text.

3. Ereignissynthese: Globale CoreGraphics-Klicks, Tippen, Tastendrücke und Scrollen im unsicheren Modus erfordern Ereignis-Posting-Zugriff. Semantische Accessibility-Aktionen verwenden diesen globalen Fallback nicht.

4. Automation: Kann von macOS nur angefordert werden, wenn der unsichere Modus aktiviert ist und run_applescript ein Ereignis an eine andere Anwendung sendet. Kern-Eingabe- und Hintergrund-Tools verwenden den nativen Helfer anstelle von System Events.

Rufen Sie get_capabilities vor geschützten Operationen auf. Die Berechtigungsprüfung verwendet Apples Preflight-APIs und öffnet keine Berechtigungsaufforderung. Wenn der Zugriff fehlt, geben Screenshot-/OCR- und globale Eingabepfade SCREEN_RECORDING_PERMISSION_REQUIRED oder INPUT_POSTING_PERMISSION_REQUIRED vor der Ausführung zurück. Gewähren Sie den Zugriff manuell in den Systemeinstellungen und verbinden Sie dann den MCP erneut, wenn der Host weiterhin veralteten Datenschutzstatus hält.

macOS kann dennoch einen Neustart der Host-App nach einer neu gewährten Datenschutzberechtigung erfordern. Dies wird von macOS erzwungen; der Server fordert nicht wiederholt oder unzusammenhängende Berechtigungen an.

Hintergrund-UI-Automatisierung ist kooperativ: macOS kann Accessibility-Elemente in einem anderen Prozess adressieren, aber eine Anwendung kann gezielte Tastaturereignisse ignorieren oder ihre Bezeichner in einer späteren Version ändern. Diese Tools geben in solchen Fällen explizite nicht unterstützte/nicht bestätigte Fehler zurück, anstatt die App zu aktivieren oder einen falschen Erfolg zu melden.

🔌 MCP-Konfiguration

Fügen Sie diesen Server zu Ihrer MCP-Client-Konfiguration hinzu:

Antigravity / Claude Desktop / Cursor / Windsurf

Fügen Sie zu Ihrer mcp_config.json / claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "macos-computer-use": {
      "command": "node",
      "args": ["/absolute/path/to/macos-computer-use/server.mjs"]
    }
  }
}

🧪 Testen des nativen Swift-Helfers direkt

Sie können die native Binärdatei direkt von Ihrem Terminal aus testen:

# Display resolution and scaling
./native_helper size

# List active Chrome windows in Z-order
./native_helper list_windows "Google Chrome"

# Find a button or text on screen with Apple Vision OCR in ~30ms
./native_helper find_text "Search" "Google Chrome"

# Reactively wait for dynamic text to appear
./native_helper wait_for_text "quantum" "Google Chrome" nil 5.0

Führen Sie die automatisierten Fail-Closed- und Matching-Regressionen aus:

npm test

Verifizieren Sie die semantische Inspektion gegen ein Hintergrund-Rechnerfenster:

npm run test:background -- Calculator

Mit geöffnetem Rechner und Systemeinstellungen führen Sie die Live-Native-App-Smoke-Suite aus. Der Test aktiviert den unsicheren Modus, weil er AppleScript verwendet, um TextEdit-Fixtures zu erstellen und zu bereinigen:

npm run test:live

Mutierende Tool-Ergebnisse enthalten ein execution-Objekt mit einem versionierten Vertrag, Zustellungsmethode, Verifizierungsstufe, Vordergrund-Erhaltungszustand und Ziel. Koordinatenbasierte Aktionen behalten status: "delivered_unverified"; verifizieren Sie folgenreiche Nachzustände mit semantischer Inspektion, OCR oder einem Screenshot.

Der MCP-Server startet einen Cursor-Overlay-Prozess verzögert beim ersten Klick oder Scrollen und stoppt ihn, wenn die MCP-Verbindung geschlossen wird. Das Overlay fängt niemals Mauseingaben ab, verbindet alle Spaces und Vollbildfenster und meldet cursorOverlay.status: "unavailable", ohne die angeforderte Aktion zu blockieren, wenn AppKit es nicht anzeigen kann.

📦 Veröffentlichung

Pushes auf main führen den npm-Publishing-Workflow aus. Um eine neue Version zu veröffentlichen, aktualisieren Sie die Version in package.json und package-lock.json vor dem Mergen. Versionen, die bereits auf npm existieren, werden getestet und übersprungen.

📄 Lizenz

MIT © John Oba