Claude KVM

Claude KVM

Accès à distance, Intelligence Artificielle

claude-kvm.ai

Claude KVM est un outil MCP qui contrôle des environnements de bureau à distance via VNC. Il se compose d'une fine couche proxy JS (serveur MCP) et d'un démon VNC natif Swift s'exécutant sur votre système macOS.

[!TIP] Phantom-WG pourrait être une excellente alternative pour vous. Isolez votre serveur VNC au sein de votre propre réseau tout en bénéficiant des performances d'un VPN auto-hébergé et des fonctionnalités de confidentialité supplémentaires que vous gagnez au passage.

Tests en conditions réelles

• Test d'intégration
• Test d'intégration Mac
• Test Calculatrice Mac
• Test Calculatrice scientifique Mac
• Test Navigation Safari Mac
• Test Glisser-déposer Mac
• Test Échecs Mac
• Test Échecs Mac Direct
• Test Installation Phantom-WG Mac

[!NOTE] Les tests sont menés de manière transparente sur GitHub Actions — chaque étape est visible dans l'environnement CI. À la fin de chaque test, que l'intégration réussisse ou échoue, vous trouverez des captures d'écran de chaque étape entreprise par l'agent durant la session, ainsi qu'un enregistrement vidéo .mp4 qui capture l'intégralité de la session. En examinant ces enregistrements et captures d'écran, vous pouvez observer comment l'agent a progressé à travers chaque étape, combien de temps la tâche a pris et quelles décisions ont été prises en fonction de l'invite système. Vous pouvez utiliser ces exemples comme référence lors de l'élaboration de vos propres invites système ou instructions pour le serveur MCP dans votre propre environnement.

[!WARNING] Les artefacts attachés à ces exécutions peuvent avoir expiré en raison de la politique de rétention des artefacts de GitHub. Des copies persistantes sont préparées via le workflow Persist Artifacts et sont toujours accessibles par ID d'exécution depuis le répertoire artifacts/ sur la branche press-kit.

Architecture

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

Couches

Couche	Langage	Rôle	Communication
Proxy MCP	JavaScript (Node.js)	Communique avec Claude via le protocole MCP, gère le cycle de vie du démon	stdio JSON-RPC
Démon VNC	Swift/C (Apple Silicon)	Connexion VNC, capture d'écran, injection d'entrées souris/clavier	stdin/stdout PC (NDJSON)

Protocole PC (Procedure Call)

La communication entre le proxy et le démon utilise le protocole PC sur 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":{...}}

Mise à l'échelle des coordonnées

La résolution native du serveur VNC est réduite pour s'adapter à --max-dimension (par défaut : 1280px). Claude travaille de manière plus cohérente avec des coordonnées mises à l'échelle — le démon gère la conversion en arrière-plan :

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

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

Stratégie d'écran

Claude minimise le coût en tokens avec une approche de vérification progressive :

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 utilise le framework Apple Vision pour l'OCR sur l'appareil. Renvoie le contenu textuel avec les coordonnées du cadre englobant dans l'espace mis à l'échelle — permet un ciblage précis des clics sans consommer de tokens de vision.

---

Installation

Prérequis

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

Démon

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

[!NOTE] claude-kvm-daemon est compilé et signé numériquement via CI (GitHub Actions). La sortie de construction est empaquetée en deux formats : une archive .tar.gz pour la distribution Homebrew et une image disque .dmg pour la notarisation. Le DMG est soumis aux serveurs Apple pour notarisation au sein du même workflow — le processus peut être suivi depuis les journaux CI. Le DMG notarié est disponible en tant qu'artefact CI ; l'archive .tar.gz est également publiée en tant que release sur le dépôt. L'installation Homebrew suit cette release.

• Release · Code Source
• Build LibVNC · Branche LibVNC
• Tap Homebrew

Configuration MCP

Créez un fichier .mcp.json dans le répertoire de votre projet :

{
  "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] L'outil est testé de bout en bout via CI — Claude exécute des tâches sur VNC tandis qu'un modèle de vision indépendant observe et vérifie les résultats. Consultez le Test d'intégration pour les exécutions de workflow en direct, les invites système et les enregistrements de démonstration.

Configuration

Proxy MCP (ENV)

Paramètre	Défaut	Description
VNC_HOST	127.0.0.1	Adresse du serveur VNC
VNC_PORT	5900	Numéro de port VNC
VNC_USERNAME		Nom d'utilisateur (requis pour ARD)
VNC_PASSWORD		Mot de passe
CLAUDE_KVM_DAEMON_PATH	claude-kvm-daemon	Chemin du binaire du démon (inutile si déjà dans le PATH)
CLAUDE_KVM_DAEMON_PARAMETERS		Arguments CLI supplémentaires pour le démon

Paramètres du démon (CLI)

Arguments supplémentaires passés au démon via CLAUDE_KVM_DAEMON_PARAMETERS :

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

Paramètre	Défaut	Description
--max-dimension	1280	Dimension maximale de mise à l'échelle de l'affichage (px)
--connect-timeout		Délai de connexion VNC (secondes)
--bits-per-sample		Bits par échantillon de pixel
--no-reconnect		Désactiver la reconnexion automatique
-v, --verbose		Journalisation verbeuse (stderr)

Configuration d'exécution (PC)

Tous les paramètres de temporisation et d'affichage sont configurables à l'exécution via la méthode configure. Utilisez get_timing pour inspecter les valeurs actuelles.

Définir la temporisation :

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

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

Modifier la mise à l'échelle de l'affichage :

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

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

Réinitialiser aux valeurs par défaut :

{"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}}

Obtenir les valeurs actuelles :

{"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}}

Paramètre	Défaut	Description
max_dimension	1280	Dimension max de capture d'écran
cursor_crop_radius	150	Rayon de recadrage du curseur (px)
click_hold_ms	50	Durée de maintien du clic
double_click_gap_ms	50	Délai entre deux clics
hover_settle_ms	400	Attente de stabilisation du survol
drag_position_ms	30	Attente de position avant glissement
drag_press_ms	50	Seuil de maintien pour appui glissement
drag_step_ms	5	Entre les points d'interpolation
drag_settle_ms	30	Stabilisation avant relâchement
drag_pixels_per_step	20	Densité de points par pixel
drag_min_steps	10	Étapes d'interpolation min
scroll_press_ms	10	Intervalle appui-relâchement défilement
scroll_tick_ms	20	Délai inter-tic
key_hold_ms	30	Durée de maintien de touche
combo_mod_ms	10	Délai de stabilisation du modificateur
type_key_ms	20	Maintien de touche pendant la frappe
type_inter_key_ms	20	Délai inter-caractères
type_shift_ms	10	Stabilisation touche Maj
paste_settle_ms	30	Attente après écriture dans le presse-papiers

---

Outils

Toutes les opérations sont effectuées via un seul outil vnc_command :

Écran

Action	Paramètres	Description
screenshot		Capture PNG plein écran
cursor_crop		Recadrage autour du curseur avec superposition de réticule
diff_check		Détecter les changements d'écran par rapport à la référence
set_baseline		Sauvegarder l'écran actuel comme référence de diff

Souris

Action	Paramètres	Description
mouse_click	x, y, button?	Clic (gauche|droit|milieu)
mouse_double_click	x, y	Double clic
mouse_move	x, y	Déplacer le curseur
hover	x, y	Déplacer + attente de stabilisation
nudge	dx, dy	Mouvement relatif du curseur
mouse_drag	x, y, toX, toY	Glisser du début à la fin
scroll	x, y, direction, amount?	Défilement (haut|bas|gauche|droite)

Clavier

Action	Paramètres	Description
key_tap	key	Appui sur une touche simple (entrée|échap|tab|espace|...)
key_combo	key ou keys	Combinaison de modificateurs ("cmd+c" ou ["cmd","shift","3"])
key_type	text	Saisir du texte caractère par caractère
paste	text	Coller du texte via le presse-papiers

Détection

Action	Paramètres	Description
detect_elements		Détection de texte OCR avec cadres englobants (Apple Vision)

Renvoie les éléments de texte avec les coordonnées du cadre englobant dans l'espace mis à l'échelle :

{"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}}

Configuration

Action	Paramètres	Description
configure	{<params>}	Définir les paramètres de temporisation/affichage à l'exécution
configure	{reset: true}	Réinitialiser tous les paramètres aux valeurs par défaut
get_timing		Obtenir les paramètres actuels de temporisation + affichage

Contrôle

Action	Paramètres	Description
wait	ms?	Attendre (défaut 500ms)
health		Statut de la connexion + infos d'affichage
shutdown		Arrêt gracieux du démon

---

Authentification

Méthodes d'authentification VNC prises en charge :

• VNC Auth — défi-réponse basé sur mot de passe (DES)
• ARD — Apple Remote Desktop (Diffie-Hellman + AES-128-ECB)

macOS est auto-détecté via la demande d'identification de type 30 ARD. Lorsqu'il est détecté, les touches Meta sont remappées sur Super (compatibilité avec la touche Commande).

---

[!NOTE] Vous utilisez un Mac bare-metal ? Consultez les Astuces de préparation pour Mac M1 pour le renforcement VNC, le tunneling SSH et des conseils de stabilité de session.

---

"Claude" est une marque déposée d'Anthropic, PBC. Ce projet n'est pas affilié à ni soutenu par Anthropic.

Copyright (c) 2026 Riza Emre ARAS — Licence MIT