Claude KVM

Claude KVM

Fernzugriff, Künstliche Intelligenz

claude-kvm.ai

Claude KVM ist ein MCP-Tool, das Remote-Desktop-Umgebungen über VNC steuert. Es besteht aus einer schlanken JS-Proxyschicht (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

• Integrationstest
• Mac-Integrationstest
• Mac-Rechnertest
• Mac-Test des wissenschaftlichen Rechners
• Mac-Safari-Browsing-Test
• Mac-Drag-&-Drop-Test
• Mac-Schachtest
• Mac-Schach-Direkttest
• Mac-Phantom-WG-Installationstest

[!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 GitHub-Artefakte abgelaufen. Dauerhafte Kopien werden über den Persist Artifacts-Workflow erstellt und können jederzeit anhand der Run-ID aus dem artifacts/-Verzeichnis 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-Verbindungszeitüberschreitung (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 configure-Methode 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-Abstandsverzögerung
hover_settle_ms	400	Hover-Beruhigungswartezeit
drag_position_ms	30	Wartezeit vor Ziehvorgang
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	Inter-Tick-Verzögerung
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	Inter-Zeichen-Verzögerung
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 nach 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 (Command-Tasten-Kompatibilität) umgemappt.

---

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

---

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

Copyright (c) 2026 Riza Emre ARAS — MIT-Lizenz