Claude KVM

oficial

🤖 ⚡️ MCP server ( MacOS) — controlar escritor

Documentación

Claude KVM

Acceso Remoto, Inteligencia Artificial

Claude KVM es una herramienta MCP que controla entornos de escritorio remotos a través de VNC. Consiste en una capa proxy ligera en JS (servidor MCP) y un demonio VNC nativo de plataforma en Swift que se ejecuta en tu sistema macOS.

[!TIP] Phantom-WG podría ser una gran alternativa para ti. Aísla tu servidor VNC dentro de tu propia red mientras disfrutas del rendimiento de una VPN autoalojada con las características adicionales de privacidad que obtienes en el proceso.

Pruebas en Vivo

[!NOTE] Las pruebas se realizan de forma transparente en GitHub Actions — cada paso es visible en el entorno de CI. Al final de cada prueba, ya sea que la integración pase o falle, encontrarás capturas de pantalla de cada paso que el agente tomó durante la sesión, junto con una grabación de video .mp4 que captura toda la sesión. Al revisar estas grabaciones y capturas de pantalla, puedes observar cómo el agente progresó a través de cada etapa, cuánto tiempo tomó la tarea y qué decisiones se tomaron basándose en el prompt del sistema. Puedes usar estos ejemplos como referencia al crear tus propios prompts de sistema o instrucciones para el servidor MCP en tu propio entorno.

[!WARNING] Los artefactos adjuntos a estas ejecuciones pueden haber expirado debido a la política de retención de artefactos de GitHub. Se preparan copias persistentes a través del flujo de trabajo Persist Artifacts y siempre se puede acceder a ellas por ID de ejecución desde el directorio artifacts/ en la rama press-kit.

Arquitectura

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

Capas

Capa	Lenguaje	Rol	Comunicación
Proxy MCP	JavaScript (Node.js)	Se comunica con Claude a través del protocolo MCP, gestiona el ciclo de vida del demonio	stdio JSON-RPC
Demonio VNC	Swift/C (Apple Silicon)	Conexión VNC, captura de pantalla, inyección de entrada de ratón/teclado	stdin/stdout PC (NDJSON)

Protocolo PC (Llamada a Procedimiento)

La comunicación entre el proxy y el demonio utiliza el protocolo PC sobre 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":{...}}

Escalado de Coordenadas

La resolución nativa del servidor VNC se reduce para ajustarse dentro de --max-dimension (por defecto: 1280px). Claude trabaja de manera más consistente con coordenadas escaladas — el demonio maneja la conversión en segundo plano:

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

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

Estrategia de Pantalla

Claude minimiza el costo de tokens con un enfoque de verificación progresiva:

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 utiliza el framework Apple Vision para OCR en el dispositivo. Devuelve contenido de texto con coordenadas de cuadro delimitador en espacio escalado — permite apuntar con precisión sin consumir tokens de visión.

Instalación

Requisitos

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

Demonio

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

[!NOTE] claude-kvm-daemon se compila y firma mediante CI (GitHub Actions). La salida de la compilación se empaqueta en dos formatos: un archivo .tar.gz para distribución Homebrew y una imagen de disco .dmg para notarización. El DMG se envía a los servidores de Apple para notarización dentro del mismo flujo de trabajo — el proceso se puede rastrear desde los registros de CI. El DMG notarizado está disponible como un Artefacto de CI; el .tar.gz archivado también se publica como una versión en el repositorio. La instalación de Homebrew rastrea esta versión.

Versión · Código Fuente

Compilación LibVNC · Rama LibVNC

Homebrew Tap

Configuración MCP

Crea un archivo .mcp.json en el directorio de tu proyecto:

{
  "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] La herramienta se prueba de extremo a extremo a través de CI — Claude ejecuta tareas sobre VNC mientras un modelo de visión independiente observa y verifica los resultados. Consulta la Prueba de Integración para ejecuciones de flujo de trabajo en vivo, prompts de sistema y grabaciones de demostración.

Configuración

Proxy MCP (ENV)

Parámetro	Predeterminado	Descripción
`VNC_HOST`	`127.0.0.1`	Dirección del servidor VNC
`VNC_PORT`	`5900`	Número de puerto VNC
`VNC_USERNAME`		Nombre de usuario (requerido para ARD)
`VNC_PASSWORD`		Contraseña
`CLAUDE_KVM_DAEMON_PATH`	`claude-kvm-daemon`	Ruta del binario del demonio (no necesaria si ya está en PATH)
`CLAUDE_KVM_DAEMON_PARAMETERS`		Argumentos CLI adicionales para el demonio

Parámetros del Demonio (CLI)

Argumentos adicionales pasados al demonio a través de CLAUDE_KVM_DAEMON_PARAMETERS:

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

Parámetro	Predeterminado	Descripción
`--max-dimension`	`1280`	Dimensión máxima de escalado de pantalla (px)
`--connect-timeout`		Tiempo de espera de conexión VNC (segundos)
`--bits-per-sample`		Bits por muestra de píxel
`--no-reconnect`		Deshabilitar reconexión automática
`-v, --verbose`		Registro detallado (stderr)

Configuración en Tiempo de Ejecución (PC)

Todos los parámetros de temporización y visualización son configurables en tiempo de ejecución a través del método configure. Usa get_timing para inspeccionar los valores actuales.

Establecer temporización:

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

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

Cambiar escalado de pantalla:

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

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

Restablecer a valores predeterminados:

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

Obtener valores actuales:

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

Parámetro	Predeterminado	Descripción
`max_dimension`	`1280`	Dimensión máxima de captura de pantalla
`cursor_crop_radius`	`150`	Radio de recorte del cursor (px)
`click_hold_ms`	`50`	Duración de pulsación de clic
`double_click_gap_ms`	`50`	Retardo entre doble clic
`hover_settle_ms`	`400`	Espera de asentamiento al pasar el cursor
`drag_position_ms`	`30`	Espera de posición previa al arrastre
`drag_press_ms`	`50`	Umbral de pulsación para arrastre
`drag_step_ms`	`5`	Entre puntos de interpolación
`drag_settle_ms`	`30`	Asentamiento antes de soltar
`drag_pixels_per_step`	`20`	Densidad de puntos por píxel
`drag_min_steps`	`10`	Pasos mínimos de interpolación
`scroll_press_ms`	`10`	Intervalo de pulsación-liberación de desplazamiento
`scroll_tick_ms`	`20`	Retardo entre ticks
`key_hold_ms`	`30`	Duración de pulsación de tecla
`combo_mod_ms`	`10`	Retardo de asentamiento de modificador
`type_key_ms`	`20`	Pulsación de tecla durante escritura
`type_inter_key_ms`	`20`	Retardo entre caracteres
`type_shift_ms`	`10`	Asentamiento de tecla Shift
`paste_settle_ms`	`30`	Espera posterior a escritura en portapapeles

Herramientas

Todas las operaciones se realizan a través de una única herramienta vnc_command:

Pantalla

Acción	Parámetros	Descripción
`screenshot`		Captura PNG de pantalla completa
`cursor_crop`		Recorte alrededor del cursor con superposición de punto de mira
`diff_check`		Detectar cambios en pantalla contra línea base
`set_baseline`		Guardar pantalla actual como referencia de diferencias

Ratón

Acción	Parámetros	Descripción
`mouse_click`	`x, y, button?`	Clic (izquierdo\|derecho\|medio)
`mouse_double_click`	`x, y`	Doble clic
`mouse_move`	`x, y`	Mover cursor
`hover`	`x, y`	Mover + espera de asentamiento
`nudge`	`dx, dy`	Movimiento relativo del cursor
`mouse_drag`	`x, y, toX, toY`	Arrastrar de inicio a fin
`scroll`	`x, y, direction, amount?`	Desplazar (arriba\|abajo\|izquierda\|derecha)

Teclado

Acción	Parámetros	Descripción
`key_tap`	`key`	Pulsación de tecla única (enter\|escape\|tab\|space\|...)
`key_combo`	`key` o `keys`	Combinación de modificador ("cmd+c" o ["cmd","shift","3"])
`key_type`	`text`	Escribir texto carácter por carácter
`paste`	`text`	Pegar texto a través del portapapeles

Detección

Acción	Parámetros	Descripción
`detect_elements`		Detección de texto OCR con cuadros delimitadores (Apple Vision)

Devuelve elementos de texto con coordenadas de cuadro delimitador en espacio escalado:

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

Configuración

Acción	Parámetros	Descripción
`configure`	`{<params>}`	Establecer parámetros de temporización/visualización en tiempo de ejecución
`configure`	`{reset: true}`	Restablecer todos los parámetros a valores predeterminados
`get_timing`		Obtener parámetros actuales de temporización + visualización

Control

Acción	Parámetros	Descripción
`wait`	`ms?`	Esperar (predeterminado 500ms)
`health`		Estado de conexión + información de pantalla
`shutdown`		Apagado ordenado del demonio

Autenticación

Métodos de autenticación VNC soportados:

VNC Auth — desafío-respuesta basado en contraseña (DES)
ARD — Apple Remote Desktop (Diffie-Hellman + AES-128-ECB)

macOS se detecta automáticamente a través de la solicitud de credencial de tipo de autenticación ARD 30. Cuando se detecta, las teclas Meta se reasignan a Super (compatibilidad con tecla Command).

[!NOTE] ¿Ejecutándose en un Mac con hardware dedicado? Consulte los Trucos de preparación para Mac M1 para obtener consejos sobre refuerzo de VNC, tunelización SSH y estabilidad de la sesión.

"Claude" es una marca registrada de Anthropic, PBC. Este proyecto no está afiliado ni respaldado por Anthropic.