Claude KVM

offiziell

🤖 ⚡️ MCP-Server ( MacOS) — steuere entfernte Desktops über VNC

Dokumentation

Claude KVM

Fernzugriff, Künstliche Intelligenz

Claude KVM ist ein MCP-Tool, das Remote-Desktop-Umgebungen über VNC steuert. Es besteht aus einer schlanken JS-Proxy-Schicht (MCP-Server) und einem plattformnativen Swift-VNC-Daemon, der auf Ihrem macOS-System läuft.

[!TIP] Phantom-WG könnte eine großartige Alternative für Sie sein. Isolieren Sie Ihren VNC-Server in Ihrem eigenen Netzwerk und genießen Sie dabei die Leistung eines selbst gehosteten VPNs mit den zusätzlichen Datenschutzfunktionen, die Sie dabei erhalten.

Live-Testläufe

[!NOTE] Tests werden transparent auf GitHub Actions durchgeführt – jeder Schritt ist in der CI-Umgebung sichtbar. Am Ende jedes Tests, unabhängig davon, ob die Integration erfolgreich ist oder fehlschlägt, finden Sie Screenshots jedes Schritts, den der Agent während der Sitzung unternommen hat, zusammen mit einer .mp4-Videoaufzeichnung, die die gesamte Sitzung erfasst. Durch die Überprüfung dieser Aufzeichnungen und Screenshots können Sie beobachten, wie der Agent jede Phase durchlief, wie lange die Aufgabe dauerte und welche Entscheidungen basierend auf dem System-Prompt getroffen wurden. Sie können diese Beispiele als Referenz verwenden, wenn Sie Ihre eigenen System-Prompts oder Anweisungen für den MCP-Server in Ihrer eigenen Umgebung erstellen.

[!WARNING] An diese Läufe angehängte Artefakte sind möglicherweise aufgrund der Aufbewahrungsrichtlinie für Artefakte von GitHub abgelaufen. Dauerhafte Kopien werden über den Workflow Persist Artifacts erstellt und können jederzeit anhand der Run-ID aus dem Verzeichnis artifacts/ im Press-Kit-Branch abgerufen werden.

Architektur

graph TB
    subgraph MCP["MCP Client (Claude)"]
        AI["Claude"]
    end

    subgraph Proxy["claude-kvm · MCP Proxy (stdio)"]
        direction TB
        Server["MCP Server<br/><code>index.js</code>"]
        Tools["Tool Definitions<br/><code>tools/index.js</code>"]
        Server --> Tools
    end

    subgraph Daemon["claude-kvm-daemon · Native VNC Client (stdin/stdout)"]
        direction TB
        CMD["Command Handler<br/><i>PC Dispatch</i>"]
        Scale["Display Scaling<br/><i>Scaled ↔ Native</i>"]

        subgraph Screen["Screen"]
            Capture["Frame Capture<br/><i>PNG · Crop · Diff</i>"]
            OCR["OCR Detection<br/><i>Apple Vision</i>"]
        end

        subgraph InputGroup["Input"]
            Mouse["Mouse<br/><i>Click · Drag · Move · Scroll</i>"]
            KB["Keyboard<br/><i>Tap · Combo · Type · Paste</i>"]
        end

        VNC["VNC Bridge<br/><i>LibVNCClient 0.9.15</i>"]

        CMD --> Scale
        Scale --> Capture
        Scale --> Mouse
        Scale --> KB
        Capture -.->|"framebuffer"| VNC
        Mouse -->|"pointer events"| VNC
        KB -->|"key events"| VNC
    end

    subgraph Target["Target Machine"]
        VNC_Server["VNC Server<br/><i>:5900</i>"]
        Desktop["Desktop Environment"]
        VNC_Server --> Desktop
    end

    AI <-->|"stdio<br/>JSON-RPC"| Server
    Server <-->|"stdin/stdout<br/>PC (NDJSON)"| CMD
    VNC <-->|"RFB Protocol<br/>TCP :5900"| VNC_Server

    classDef proxy fill:#1a1a2e,stroke:#16213e,color:#e5e5e5
    classDef daemon fill:#0f3460,stroke:#533483,color:#e5e5e5
    classDef target fill:#1a1a2e,stroke:#e94560,color:#e5e5e5

    class Server,Tools proxy
    class CMD,Scale,VNC,Capture,Mouse,KB daemon
    class VNC_Server,Desktop target

Schichten

Schicht	Sprache	Rolle	Kommunikation
MCP-Proxy	JavaScript (Node.js)	Kommuniziert mit Claude über das MCP-Protokoll, verwaltet den Daemon-Lebenszyklus	stdio JSON-RPC
VNC-Daemon	Swift/C (Apple Silicon)	VNC-Verbindung, Bildschirmaufnahme, Maus-/Tastatureingabeinjektion	stdin/stdout PC (NDJSON)

PC (Procedure Call)-Protokoll

Die Kommunikation zwischen Proxy und Daemon verwendet das PC-Protokoll über NDJSON:

Request:      {"method":"<name>","params":{...},"id":<int|string>}
Response:     {"result":{...},"id":<int|string>}
Error:        {"error":{"code":<int>,"message":"..."},"id":<int|string>}
Notification: {"method":"<name>","params":{...}}

Koordinatenskalierung

Die native Auflösung des VNC-Servers wird herunterskaliert, um in --max-dimension (Standard: 1280px) zu passen. Claude arbeitet konsistenter mit skalierten Koordinaten – der Daemon übernimmt die Konvertierung im Hintergrund:

Native:  4220 x 2568  (VNC server framebuffer)
Scaled:  1280 x 779   (what Claude sees and targets)

mouse_click(640, 400) → VNC receives (2110, 1284)

Bildschirmstrategie

Claude minimiert die Token-Kosten mit einem progressiven Verifikationsansatz:

diff_check       →  changeDetected: true/false     ~5ms    (text only, no image)
detect_elements  →  OCR text + bounding boxes      ~50ms   (text only, no image)
cursor_crop      →  crop around cursor              ~50ms   (small image)
screenshot       →  full screen capture             ~200ms  (full image)

detect_elements verwendet das Apple Vision-Framework für geräteinterne OCR. Gibt Textinhalte mit Begrenzungsrahmenkoordinaten im skalierten Raum zurück – ermöglicht präzises Klicken ohne Verbrauch von Vision-Tokens.

Installation

Voraussetzungen

macOS (Apple Silicon / aarch64)
Node.js (LTS)

Daemon

brew tap ARAS-Workspace/tap
brew install claude-kvm-daemon

[!NOTE] claude-kvm-daemon wird über CI (GitHub Actions) kompiliert und codesigniert. Die Build-Ausgabe wird in zwei Formaten verpackt: ein .tar.gz-Archiv für die Homebrew-Verteilung und ein .dmg-Disk-Image für die Notarisierung. Das DMG wird im selben Workflow zur Notarisierung an Apple-Server übermittelt – der Prozess kann anhand der CI-Protokolle verfolgt werden. Das notarisierte DMG ist als CI-Artefakt verfügbar; das archivierte .tar.gz wird auch als Release im Repository veröffentlicht. Die Homebrew-Installation verfolgt dieses Release.

Release · Quellcode

LibVNC-Build · LibVNC-Branch

Homebrew Tap

MCP-Konfiguration

Erstellen Sie eine .mcp.json-Datei in Ihrem Projektverzeichnis:

{
  "mcpServers": {
    "claude-kvm": {
      "command": "npx",
      "args": ["-y", "claude-kvm"],
      "env": {
        "VNC_HOST": "192.168.1.100",
        "VNC_PORT": "5900",
        "VNC_USERNAME": "user",
        "VNC_PASSWORD": "pass",
        "CLAUDE_KVM_DAEMON_PATH": "/opt/homebrew/bin/claude-kvm-daemon",
        "CLAUDE_KVM_DAEMON_PARAMETERS": "-v"
      }
    }
  }
}

[!NOTE] Das Tool wird End-to-End über CI getestet – Claude führt Aufgaben über VNC aus, während ein unabhängiges Vision-Modell die Ergebnisse beobachtet und verifiziert. Siehe den Integrationstest für Live-Workflow-Läufe, System-Prompts und Demo-Aufzeichnungen.

Konfiguration

MCP-Proxy (ENV)

Parameter	Standard	Beschreibung
`VNC_HOST`	`127.0.0.1`	VNC-Serveradresse
`VNC_PORT`	`5900`	VNC-Portnummer
`VNC_USERNAME`		Benutzername (erforderlich für ARD)
`VNC_PASSWORD`		Passwort
`CLAUDE_KVM_DAEMON_PATH`	`claude-kvm-daemon`	Daemon-Binärpfad (nicht benötigt, wenn bereits im PATH)
`CLAUDE_KVM_DAEMON_PARAMETERS`		Zusätzliche CLI-Argumente für den Daemon

Daemon-Parameter (CLI)

Zusätzliche Argumente, die über CLAUDE_KVM_DAEMON_PARAMETERS an den Daemon übergeben werden:

"CLAUDE_KVM_DAEMON_PARAMETERS": "--max-dimension 800 -v"

Parameter	Standard	Beschreibung
`--max-dimension`	`1280`	Maximale Anzeigeskalierungsdimension (px)
`--connect-timeout`		VNC-Verbindungstimeout (Sekunden)
`--bits-per-sample`		Bits pro Pixel-Sample
`--no-reconnect`		Automatische Wiederverbindung deaktivieren
`-v, --verbose`		Ausführliche Protokollierung (stderr)

Laufzeitkonfiguration (PC)

Alle Timing- und Anzeigeparameter sind zur Laufzeit über die Methode configure konfigurierbar. Verwenden Sie get_timing, um die aktuellen Werte zu überprüfen.

Timing festlegen:

{"method":"configure","params":{"click_hold_ms":80,"key_hold_ms":50}}

{"result":{"detail":"OK — changed: click_hold_ms, key_hold_ms"}}

Anzeigeskalierung ändern:

{"method":"configure","params":{"max_dimension":960}}

{"result":{"detail":"OK — changed: max_dimension","scaledWidth":960,"scaledHeight":584}}

Auf Standardwerte zurücksetzen:

{"method":"configure","params":{"reset":true}}

{"result":{"detail":"OK — reset to defaults","timing":{"click_hold_ms":50,"combo_mod_ms":10,"cursor_crop_radius":150,"double_click_gap_ms":50,"drag_min_steps":10,"drag_pixels_per_step":20,"drag_position_ms":30,"drag_press_ms":50,"drag_settle_ms":30,"drag_step_ms":5,"hover_settle_ms":400,"key_hold_ms":30,"max_dimension":1280,"paste_settle_ms":30,"scroll_press_ms":10,"scroll_tick_ms":20,"type_inter_key_ms":20,"type_key_ms":20,"type_shift_ms":10},"scaledWidth":1280,"scaledHeight":779}}

Aktuelle Werte abrufen:

{"method":"get_timing"}

{"result":{"timing":{"click_hold_ms":80,"combo_mod_ms":10,"cursor_crop_radius":150,"double_click_gap_ms":50,"drag_min_steps":10,"drag_pixels_per_step":20,"drag_position_ms":30,"drag_press_ms":50,"drag_settle_ms":30,"drag_step_ms":5,"hover_settle_ms":400,"key_hold_ms":50,"max_dimension":1280,"paste_settle_ms":30,"scroll_press_ms":10,"scroll_tick_ms":20,"type_inter_key_ms":20,"type_key_ms":20,"type_shift_ms":10},"scaledWidth":1280,"scaledHeight":779}}

Parameter	Standard	Beschreibung
`max_dimension`	`1280`	Maximale Screenshot-Dimension
`cursor_crop_radius`	`150`	Cursor-Zuschneideradius (px)
`click_hold_ms`	`50`	Klick-Haltedauer
`double_click_gap_ms`	`50`	Doppelklick-Pausenverzögerung
`hover_settle_ms`	`400`	Hover-Beruhigungswartezeit
`drag_position_ms`	`30`	Positionswartezeit vor Ziehen
`drag_press_ms`	`50`	Zieh-Druck-Halteschwelle
`drag_step_ms`	`5`	Zwischen Interpolationspunkten
`drag_settle_ms`	`30`	Beruhigung vor Loslassen
`drag_pixels_per_step`	`20`	Punktdichte pro Pixel
`drag_min_steps`	`10`	Minimale Interpolationsschritte
`scroll_press_ms`	`10`	Scroll-Druck-Loslass-Abstand
`scroll_tick_ms`	`20`	Verzögerung zwischen Ticks
`key_hold_ms`	`30`	Tasten-Haltedauer
`combo_mod_ms`	`10`	Modifikator-Beruhigungsverzögerung
`type_key_ms`	`20`	Tastenhalten während der Eingabe
`type_inter_key_ms`	`20`	Verzögerung zwischen Zeichen
`type_shift_ms`	`10`	Umschalttaste-Beruhigung
`paste_settle_ms`	`30`	Wartezeit nach Schreiben in die Zwischenablage

Tools

Alle Operationen werden über ein einziges vnc_command-Tool ausgeführt:

Bildschirm

Aktion	Parameter	Beschreibung
`screenshot`		Vollbild-PNG-Aufnahme
`cursor_crop`		Zuschneiden um den Cursor mit Fadenkreuz-Overlay
`diff_check`		Bildschirmänderungen gegenüber der Basislinie erkennen
`set_baseline`		Aktuellen Bildschirm als Diff-Referenz speichern

Maus

Aktion	Parameter	Beschreibung
`mouse_click`	`x, y, button?`	Klick (links
`mouse_double_click`	`x, y`	Doppelklick
`mouse_move`	`x, y`	Cursor bewegen
`hover`	`x, y`	Bewegen + Beruhigungswartezeit
`nudge`	`dx, dy`	Relative Cursorbewegung
`mouse_drag`	`x, y, toX, toY`	Von Start zu Ende ziehen
`scroll`	`x, y, direction, amount?`	Scrollen (hoch

Tastatur

Aktion	Parameter	Beschreibung
`key_tap`	`key`	Einzelner Tastendruck (enter
`key_combo`	`key` oder `keys`	Modifikator-Kombination ("cmd+c" oder ["cmd","shift","3"])
`key_type`	`text`	Text Zeichen für Zeichen eingeben
`paste`	`text`	Text über die Zwischenablage einfügen

Erkennung

Aktion	Parameter	Beschreibung
`detect_elements`		OCR-Texterkennung mit Begrenzungsrahmen (Apple Vision)

Gibt Textelemente mit Begrenzungsrahmenkoordinaten im skalierten Raum zurück:

{"method":"detect_elements"}

{"result":{"detail":"13 elements","elements":[{"confidence":1,"h":9,"text":"Finder","w":32,"x":37,"y":6},{"confidence":1,"h":9,"text":"File","w":15,"x":84,"y":6},{"confidence":1,"h":9,"text":"Edit","w":19,"x":112,"y":6},{"confidence":1,"h":9,"text":"View","w":22,"x":143,"y":6},{"confidence":1,"h":11,"text":"Go","w":15,"x":179,"y":6},{"confidence":1,"h":9,"text":"Window","w":35,"x":207,"y":6},{"confidence":1,"h":11,"text":"Help","w":22,"x":255,"y":6},{"confidence":1,"h":11,"text":"8•","w":26,"x":1161,"y":6},{"confidence":1,"h":9,"text":"Fri Feb 20 22:19","w":80,"x":1189,"y":6},{"confidence":1,"h":9,"text":"Assets","w":32,"x":1202,"y":97},{"confidence":1,"h":9,"text":"Passwords.kdbx","w":74,"x":1181,"y":168},{"confidence":1,"h":93,"text":"PHANTOM","w":633,"x":322,"y":477},{"confidence":1,"h":32,"text":"YOUR SERVER, YOUR NETWORK, YOUR PRIVACY","w":629,"x":325,"y":568}],"scaledHeight":717,"scaledWidth":1280}}

Konfiguration

Aktion	Parameter	Beschreibung
`configure`	`{<params>}`	Timing-/Anzeigeparameter zur Laufzeit festlegen
`configure`	`{reset: true}`	Alle Parameter auf Standardwerte zurücksetzen
`get_timing`		Aktuelle Timing- + Anzeigeparameter abrufen

Steuerung

Aktion	Parameter	Beschreibung
`wait`	`ms?`	Warten (Standard 500ms)
`health`		Verbindungsstatus + Anzeigeinfo
`shutdown`		Ordentliches Herunterfahren des Daemons

Authentifizierung

Unterstützte VNC-Authentifizierungsmethoden:

VNC Auth – passwortbasierte Challenge-Response (DES)
ARD – Apple Remote Desktop (Diffie-Hellman + AES-128-ECB)

macOS wird automatisch über die ARD-Auth-Typ-30-Credential-Anfrage erkannt. Bei Erkennung werden Meta-Tasten auf Super umbelegt (Befehlstasten-Kompatibilität).

[!NOTE] Laufen Sie auf einem Bare-Metal-Mac? Lesen Sie die Mac M1 Vorbereitungstricks für VNC-Härtung, SSH-Tunneling und Tipps zur Sitzungsstabilität.

"Claude" ist eine Marke von Anthropic, PBC. Dieses Projekt ist weder mit Anthropic verbunden noch wird es von Anthropic unterstützt.