macos-ui-mcp

Ein Playwright-artiges Tool, mit dem Claude die Benutzeroberfläche einer nativen macOS-App inspizieren und steuern kann, während du sie entwickelst — ohne Bildschirmaufnahme-Berechtigung.

Statt den Bildschirm zu erfassen, rendert sich die App selbst. Ein winziges, nur für Debug-Zwecke gedachtes Swift-Paket (swift-harness/) stellt den View-Baum der App und einen In-Process-PNG-Renderer über localhost HTTP bereit; ein MCP-Server (src/) macht daraus Werkzeuge, die Claude aufrufen kann: list_windows, get_ui_tree, screenshot, click, type, wait_for, invoke_action.

Siehe IDEA.md für die Design-Grundlagen, den Architekturvergleich und die Projektziele.

Claude Code ──MCP(stdio)──> macos-ui-mcp server ──HTTP──> AppMCPHarness (in your app, DEBUG only)

Layout

Related MCP server: Desktop Pilot MCP

Verwendung

1. Füge das Harness zu deiner macOS-App hinzu (nur DEBUG-Builds)

Siehe swift-harness/README.md. Eine Zeile in deinem AppDelegate:

#if DEBUG
AppMCP.start()   // opens http://127.0.0.1:8787
#endif

2. Baue den MCP-Server

npm install
npm run build

3. Registriere ihn bei Claude Code

// .mcp.json
{
  "mcpServers": {
    "macos-ui-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/macos-ui-mcp/dist/index.js"],
      "env": { "MACOS_UI_MCP_HARNESS_URL": "http://127.0.0.1:8787" }
    }
  }
}

Wenn deine App nun in einem Debug-Build läuft, bitte Claude, get_ui_tree oder screenshot aufzurufen — keine Bildschirmaufnahme-Abfrage.

Entwicklung

npm test           # 38 unit tests, no real app needed (mock harness); e2e is skipped
npm run typecheck
npm run dev         # run the server against a live harness

npm run test:e2e    # builds showcase/, launches it, runs the real tools against the
                    # real Swift harness. Needs a logged-in macOS GUI session.

npm run test:e2e ist der Beweis für die Ziele: Es prüft, dass get_ui_tree die Steuerelemente sieht, screenshot ein echtes In-Process-PNG zurückgibt und click / type die Live-UI verändern — ohne Bildschirmaufnahme-Berechtigung.

Selektorgrammatik

Verwendet von click, type, screenshot, wait_for:

click / type lehnen mehrdeutige Selektoren ab (mehr als eine Übereinstimmung) und melden die Kandidaten-IDs.

Status

• v0.1 — macOS / AppKit. Alle 7 Werkzeuge implementiert. 38 Unit-Tests + ein End-to-End-Test mit 5 Fällen, der die showcase/-App über das echte Swift-Harness steuert. Verifiziert: Baum, In-Process-PNG-Snapshot, Tippen, Text setzen, Aktions-Hooks — Bildschirmaufnahme aus.

• Noch nicht — SwiftUI-nativer Baum (derzeit nur AppKit-Introspection), Windows-Adapter, Inspektion von Drittanbieter-Apps über die Accessibility-API.

Lizenz

MIT © 2026 Thang Duong

macos-ui-mcp