Related Pages

Related topics: Quick Start Guide, Environment Variables

Installation Guide

This guide covers the complete installation process for Claude KVM, a Model Context Protocol (MCP) server that enables Claude to control remote desktops via VNC with native Apple Silicon performance and on-device OCR capabilities.

System Architecture Overview

Claude KVM consists of two primary components that work together to provide remote desktop control:

graph TD
    A["Claude Desktop"] <-->|"MCP JSON-RPC"| B["MCP Proxy<br/>(Node.js)"]
    B <-->|"PC Protocol<br/>NDJSON"| C["VNC Daemon<br/>(Swift/C)"]
    C <-->|"VNC Protocol"| D["Remote Desktop<br/>(macOS/Target)"]
    
    B -->|spawns| C
    C -->|screen capture<br/>input injection| D

Source: README.md:Layer Architecture

Prerequisites

Before installing Claude KVM, ensure your environment meets the following requirements:

Target Machine (Remote Desktop)

• Platform: macOS (Apple Silicon recommended for native performance)
• VNC Server: A VNC server must be running and accessible
• Network: The machine running Claude must have network access to the VNC server

Control Machine (Where Claude Runs)

Source: LAUNCHGUIDE.md:Requirements

Installation Steps

Step 1: Install the Native VNC Daemon

The native daemon (claude-kvm-daemon) handles low-level VNC communication and input injection. It is distributed via Homebrew.

# Add the Homebrew tap
brew tap ARAS-Workspace/tap

# Install the daemon
brew install claude-kvm-daemon

#### Daemon Build and Distribution

The daemon is built and code-signed on GitHub Actions CI:

The notarization process validates the binary with Apple, enabling Gatekeeper approval on modern macOS systems. Source: README_TR.md:Daemon Build Process

Step 2: Configure MCP Server

Create a .mcp.json file in your project directory to configure the MCP server connection:

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

Source: README_TR.md:MCP Configuration

#### Environment Variables Reference

Source: server.json:Environment Variables

Step 3: Verify Installation

After configuration, verify the installation by checking the connection status:

# Test the MCP server loads correctly
npx -y claude-kvm --help

Supported Authentication Methods

Claude KVM supports multiple VNC authentication mechanisms:

When ARD authentication is detected (auth type 30), the daemon automatically remaps Meta keys to Super for Command key compatibility on macOS targets. Source: README.md:Authentication

Daemon Installation Paths

The daemon binary is installed to different locations depending on your macOS architecture:

The MCP proxy automatically detects the correct path, but you can override it using CLAUDE_KVM_DAEMON_PATH. Source: README_TR.md:Daemon Path Configuration

Quick Start with npx

For temporary or testing purposes, you can run the MCP proxy directly without persistent configuration:

# Set environment variables and run
VNC_HOST=192.168.1.100 VNC_PORT=5900 VNC_PASSWORD=secret npx -y claude-kvm

Post-Installation: macOS-Specific Considerations

If running on bare-metal Mac hardware, review the Mac M1 Preparation Tricks guide for:

• VNC security hardening
• SSH tunneling configuration
• Session stability improvements

[!NOTE]

This is particularly relevant if you encounter VNC connection drops during extended test sessions. Source: README.md:VNC Security Note

Troubleshooting Common Installation Issues

Daemon Not Found

If you see errors about the daemon not being found:

1. Verify Homebrew installation: brew list claude-kvm-daemon
2. Check the binary exists at the expected path
3. Set CLAUDE_KVM_DAEMON_PATH explicitly in your .mcp.json

Connection Failures

VNC connection issues during long-running sessions have been reported. If experiencing connection drops:

• SSH connectivity to the target confirms the issue is VNC/ARD server-side, not the daemon
• Consider implementing reconnection logic or monitoring

Source: Community Issue #8:VNC Connection Drops

Updating Claude KVM

Version Information

Current releases:

Source: server.json:Version, Community:Daemon Releases

Related Pages

Related topics: Installation Guide, Environment Variables

Quick Start Guide

Claude KVM enables AI assistants like Claude to control remote macOS desktops via VNC. This guide walks you through prerequisites, installation, configuration, and basic workflows to get started with automated remote desktop control.

Related Pages

Related topics: PC (Procedure Call) Protocol, Coordinate Scaling

System Architecture

Overview

Claude KVM is a Model Context Protocol (MCP) server that enables Claude to control remote macOS desktops via VNC. The system bridges Claude's AI capabilities with low-level desktop automation by combining a JavaScript-based MCP proxy with a native Swift daemon.

Purpose and Scope:

• Remote desktop automation through VNC protocol
• On-device OCR using Apple Vision framework
• Action orchestration via the MCP protocol
• Cross-platform control (macOS target, any Claude host)
• Native performance on Apple Silicon hardware

Repository: ARAS-Workspace/claude-kvm Current Version: 2.0.11 (MCP Server) | 1.0.1 (Daemon) Source: server.json:14

High-Level Architecture

The system follows a layered architecture separating protocol handling from low-level VNC operations.

graph TD
    subgraph "Claude Host"
        A[Claude AI]
    end
    
    subgraph "MCP Proxy (Node.js)"
        B[MCP SDK Server]
        C[Daemon Lifecycle Manager]
        D[PC Protocol Encoder/Decoder]
    end
    
    subgraph "VNC Daemon (Swift/C)"
        E[VNC Client]
        F[Input Injector]
        G[Screen Capture]
        H[Apple Vision OCR]
    end
    
    subgraph "Remote Target (macOS)"
        I[VNC Server]
        J[Remote Desktop]
    end
    
    A --> B
    B <--> C
    C <--> D
    D <--> E
    E <--> I
    F --> J
    G --> J
    H --> J

Key Architectural Principle: The MCP proxy handles JSON-RPC communication with Claude, while the native daemon performs all VNC operations. This separation ensures that AI-related processing remains on the Claude host while performance-critical desktop operations execute natively on Apple Silicon.

Component Layers

Layer Comparison

Source: README.md:1-30

Related Pages

Related topics: System Architecture

PC (Procedure Call) Protocol

Overview

The PC (Procedure Call) Protocol is the bidirectional JSON-RPC communication layer between the MCP Proxy (Node.js/JavaScript) and the VNC Daemon (Swift/C). It operates over stdin/stdout using NDJSON (Newline Delimited JSON) format, enabling Claude Desktop to control remote desktops via VNC.

Source: README.md

Architecture

The PC Protocol sits between two distinct layers:

Source: README.md

graph LR
    subgraph Proxy["MCP Proxy Layer"]
        A[Claude Desktop]
        B[MCP Protocol Handler]
    end
    
    subgraph Daemon["VNC Daemon Layer"]
        C[PC Protocol Parser]
        D[VNC Client Module]
        E[Input Injection Module]
        F[Screen Capture Module]
    end
    
    subgraph Target["VNC Server"]
        G[VNC Server :5900]
        H[Remote Desktop]
    end
    
    A --> B
    B -->|"stdio JSON-RPC"| C
    C -->|"PC Protocol NDJSON"| D
    D <-->|"RFB Protocol"| G
    E --> G
    F --> G
    G --> H
    
    style Proxy fill:#1a1a2e,stroke:#16213e,color:#e5e5e5
    style Daemon fill:#0f3460,stroke:#533483,color:#e5e5e5
    style Target fill:#1a1a2e,stroke:#e94560,color:#e5e5e5

Message Format

All PC Protocol messages are JSON objects separated by newlines (NDJSON). Each message must be on its own line.

Source: README.md

Request Message

{"method":"<name>","params":{...},"id":<int|string>}

Response Message

{"result":{...},"id":<int|string>}

Error Message

{"error":{"code":<int>,"message":"..."},"id":<int|string>}

Notification Message

{"method":"<name>","params":{...}}

Source: README.md

Supported Procedures

Screen Actions

Source: tools/index.js

Mouse Actions

Source: tools/index.js

Keyboard Actions

Source: tools/index.js

Detection Actions

Returns text elements with bounding box coordinates in scaled space:

{
  "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}
    ],
    "scaledHeight": 717,
    "scaledWidth": 1280
  }
}

Source: README.md

Configuration Procedures

Source: README.md

Control Procedures

Source: tools/index.js

Timing Parameters

All timing parameters can be configured at runtime via the configure method.

Source: README_TR.md

Configuration Examples

Set timing parameters:

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

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

Change screen scaling:

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

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

Reset to defaults:

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

{"result":{"detail":"OK — reset to defaults","timing":{"click_hold_ms":50,"combo_mod_ms":10,...}}}

Source: README_TR.md

Coordinate System

Coordinate Scaling

The VNC server's native resolution is scaled down to fit within --max_dimension (default: 1280px). Claude works more consistently with scaled coordinates — the daemon handles the conversion transparently.

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

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

Source: README.md

Display Configuration

The health procedure returns current display dimensions:

Authentication

The PC Protocol supports two VNC authentication methods:

Source: README.md

ARD Detection

macOS is auto-detected via the ARD auth type 30 credential request. When detected, Meta keys are remapped to Super keys for Command key compatibility.

Daemon Lifecycle

The MCP proxy manages the daemon lifecycle through the PC Protocol:

sequenceDiagram
    participant Claude
    participant Proxy as MCP Proxy
    participant Daemon as VNC Daemon
    participant VNC as VNC Server
    
    Claude->>Proxy: Start MCP server
    Proxy->>Daemon: Spawn process (stdin/stdout)
    Daemon->>VNC: Connect :5900
    VNC-->>Daemon: Authentication
    Daemon-->>Proxy: Ready (health response)
    Proxy-->>Claude: MCP tools available
    
    loop Session
        Claude->>Proxy: vnc_command request
        Proxy->>Daemon: PC Protocol request
        Daemon->>VNC: RFB operations
        Daemon-->>Proxy: PC Protocol response
        Proxy-->>Claude: MCP response
    end
    
    Claude->>Proxy: shutdown request
    Proxy->>Daemon: {"method":"shutdown"}
    Daemon->>Daemon: Cleanup
    Daemon-->>Proxy: Exit

Source: index.js

Startup Configuration

The daemon is configured via environment variables:

Source: server.json

Graceful Shutdown

The proxy handles SIGINT by sending a shutdown notification:

process.on('SIGINT', () => {
  log('Shutting down...');
  if (daemon) {
    daemon.stdin.write(JSON.stringify({ method: 'shutdown' }) + '\n');
    setTimeout(() => { daemon?.kill(); process.exit(0); }, 500);
  } else {
    process.exit(0);
  }
});

Source: index.js

Known Limitations

VNC Connection Stability

During extended test sessions (~50 turns), the VNC connection may drop and the daemon may become unresponsive. SSH to the remote Mac remains active, confirming the issue is on the VNC/ARD server side — not the daemon or network layer.

Related Issue: #8 - VNC connection drops during long-running test sessions

ARD Session Management

When targeting macOS via Apple Remote Desktop, the ARD server may terminate sessions after extended inactivity. For improved stability, consider:

• Using SSH tunneling for VNC connections
• Configuring ARD server for extended session timeouts
• Implementing periodic health checks to maintain connection

Related Documentation

• MCP Server Configuration
• Tool Definitions
• Mac M1 Preparation Tricks — VNC security, SSH tunneling, and session stability

Related Pages

Related topics: System Architecture, Screen Operations

Coordinate Scaling

Coordinate scaling is a fundamental mechanism in claude-kvm that enables AI agents like Claude to interact with remote desktops at any native resolution through a consistent, normalized coordinate space. The daemon transparently maps between the scaled coordinates Claude uses and the actual pixel positions on the VNC server's framebuffer.

Overview

When connecting to a VNC server, the remote desktop may have a native resolution far exceeding what is practical for AI processing. High-resolution displays (e.g., 4K, Retina, or multi-monitor setups) would generate enormous screenshots and require precise coordinate calculations that could exceed reasonable token budgets. Source: README.md

The coordinate scaling system solves this by:

1. Downscaling the framebuffer capture to fit within a configurable maximum dimension
2. Presenting scaled coordinates to Claude for all operations
3. Upscaling coordinates back to native resolution before sending to the VNC server

This approach allows Claude to work consistently with predictable coordinate ranges regardless of the actual remote display size. Source: README.md

Architecture

The scaling system involves multiple components across the proxy and daemon layers:

graph TD
    subgraph Proxy["MCP Proxy (Node.js)"]
        Tools["Tools Definition<br/>(tools/index.js)"]
        Server["Server Handler"]
    end
    
    subgraph Daemon["VNC Daemon (Swift/C)"]
        Scale["Scale Module"]
        Capture["Screen Capture"]
        Mouse["Mouse Controller"]
        VNC["VNC Bridge<br/>(LibVNCClient)"]
    end
    
    Tools -->|"x, y bounds<br/>from health"| Server
    Server -->|"NDJSON<br/>{method, params}"| Scale
    Scale -->|"scaled coords"| Mouse
    Scale -->|"native coords"| VNC
    Capture -->|"native framebuffer"| Scale
    Scale -->|"scaled PNG"| Server
    
    classDef proxy fill:#1a1a2e,stroke:#16213e,color:#e5e5e5
    classDef daemon fill:#0f3460,stroke:#533483,color:#e5e5e5
    
    class Tools,Server proxy
    class Scale,Capture,Mouse,VNC daemon

Source: README.md

Coordinate Transformation

The transformation follows a simple aspect-ratio-preserving algorithm. The scaled dimensions maintain the same aspect ratio as the native framebuffer while ensuring neither width nor height exceeds max_dimension.

Scaling Formula

scale_factor = max_dimension / max(native_width, native_height)
scaled_width = round(native_width * scale_factor)
scaled_height = round(native_height * scale_factor)

Coordinate Mapping

When Claude specifies a coordinate in the scaled space, the daemon applies the inverse transformation:

native_x = round(scaled_x / scale_factor)
native_y = round(scaled_y / scale_factor)

Example Transformation

For a native resolution of 4220×2568 scaled to a maximum dimension of 1280:

scale_factor = 1280 / 4220 ≈ 0.303
scaled_width = round(4220 * 0.303) = 1280
scaled_height = round(2568 * 0.303) = 779

When Claude clicks at scaled coordinates (640, 400):

native_x = round(640 / 0.303) ≈ 2110
native_y = round(400 / 0.303) ≈ 1284

Source: README.md

Configuration Options

CLI Parameter

The --max-dimension flag controls the maximum dimension at daemon startup:

# Launch with custom max dimension
claude-kvm-daemon --max-dimension 1920 --host 192.168.1.100 --port 5900

Source: README_TR.md

Runtime Configuration

The configure method allows changing the max dimension during operation:

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

Response:

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

This immediately re-scales the display and recalculates all coordinate bounds. Source: README_TR.md

All Timing/Display Parameters

The following parameters affect timing behavior related to coordinate operations:

Source: README_TR.md

Tools Using Scaled Coordinates

All mouse and scroll operations accept coordinates in the scaled space. The daemon automatically transforms them to native coordinates before sending to the VNC server.

Mouse Actions

Scroll Actions

Input Validation

The tools definition validates that all coordinates fall within the scaled bounds:

x: z.number().int().min(0).max(width - 1).optional().describe('X coordinate'),
y: z.number().int().min(0).max(height - 1).optional().describe('Y coordinate'),
toX: z.number().int().min(0).max(width - 1).optional().describe('Drag target X'),
toY: z.number().int().min(0).max(height - 1).optional().describe('Drag target Y'),

Where width and height are the current scaled dimensions obtained from the daemon's health response. Source: tools/index.js

Querying Current State

Health Check

The health action returns the current scaled dimensions:

{"action":"health"}

Response includes:

{
  "result": {
    "scaledWidth": 1280,
    "scaledHeight": 779,
    ...
  }
}

Get Timing

The get_timing action returns all current timing and display parameters:

{"action":"get_timing"}

Reset to Defaults

To reset all parameters including max_dimension to defaults:

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

Source: README_TR.md

Detection with Bounding Boxes

When using detect_elements for OCR, bounding box coordinates are returned in scaled space:

{"action":"detect_elements"}

Response:

{
  "result": {
    "scaledWidth": 1280,
    "scaledHeight": 717,
    "elements": [
      {"confidence":1,"h":9,"text":"Finder","w":32,"x":37,"y":6},
      {"confidence":1,"h":93,"text":"PHANTOM","w":633,"x":322,"y":477}
    ]
  }
}

These coordinates can be directly used with mouse actions without any conversion. Source: README.md

Practical Usage Patterns

Progressive Verification Strategy

Claude uses a tiered approach to minimize token usage while maintaining accuracy:

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

This strategy allows Claude to verify changes at low cost before committing to expensive screenshot operations.

Clicking Text Elements

A common workflow combines OCR detection with coordinate-based clicking:

1. Call detect_elements to find text and their bounding boxes
2. Calculate center point of target element
3. Call mouse_click with scaled coordinates

// After detect_elements returns {"text":"Submit","x":100,"y":200,"w":80,"h":30}
// Click center of element
clickX = x + w/2 = 100 + 40 = 140
clickY = y + h/2 = 200 + 15 = 215
mouse_click(140, 215)

Related Features

Known Limitations

VNC Connection Stability

During extended test sessions (~50 turns), VNC connections may drop. SSH connections remain active, indicating the issue is at the VNC/ARD server layer rather than the daemon. This affects coordinate operations that require active connection.

Issue: #8

Related Pages

Related topics: OCR Detection, Coordinate Scaling

Screen Operations

Screen Operations provide the visual foundation for Claude KVM's remote desktop control capabilities. These operations capture the remote display state, enable visual comparison, and integrate with OCR detection to support AI-driven automation workflows.

Overview

The Screen module delivers four primary capabilities through the vnc_command tool:

Screen capture operations form the observe phase in the standard automation pattern: screenshot → analyze → act → verify. Each capture operates on the scaled display space, ensuring coordinates align with mouse and keyboard input targets. Source: README.md

Coordinate System

The VNC server's native resolution is scaled down to fit within --max-dimension (default: 1280px). Claude works more consistently with scaled coordinates — the daemon handles the conversion in the background. Source: README.md

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

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

All screen coordinates returned by screen operations use scaled space, matching the coordinate system expected by mouse and keyboard actions. Source: README_TR.md

Screenshot Capture

Full Screen Capture

The screenshot action captures the entire remote display as a PNG image. This is the primary observation mechanism for AI-driven desktop automation.

{"action": "screenshot"}

Response includes the image data encoded as base64, along with display metadata:

{
  "result": {
    "image": "<base64-encoded-png>",
    "width": 1280,
    "height": 779
  }
}

Performance Characteristics

Source: README_TR.md

Cursor Crop

The cursor_crop action captures a cropped region centered on the current cursor position with a crosshair overlay. This is useful for focusing on UI elements near the pointer during detailed automation tasks.

{"action": "cursor_crop"}

The action uses a configurable crop radius (default: 150px) around the cursor position. Source: tools/index.js

Visual Diff

Visual diff operations enable verification of state changes after performing actions, which is critical for reliable automation scripts.

Workflow

graph TD
    A[Initial Screen] --> B[set_baseline]
    B --> C[Perform Actions]
    C --> D[diff_check]
    D --> E{Changes Detected?}
    E -->|Yes| F[Continue Workflow]
    E -->|No| G[Retry or Debug]

Set Baseline

The set_baseline action saves the current screen state as a reference for future diff comparisons:

{"action": "set_baseline"}

{"result": {"detail": "Baseline saved"}}

Diff Check

The diff_check action compares the current screen against the saved baseline and returns whether changes were detected:

{"action": "diff_check"}

{
  "result": {
    "changed": true,
    "diffPixels": 1247,
    "percentChanged": 0.125
  }
}

This pattern is particularly valuable in CI/CD environments where step-by-step verification ensures automation reliability. Source: README.md

Integration with OCR Detection

Screen operations integrate with detect_elements to provide text-aware automation:

1. Screenshot captures the display
2. detect_elements performs OCR via Apple Vision on the captured frame
3. Returns text elements with bounding boxes in scaled coordinates:

{
  "result": {
    "elements": [
      {"confidence": 1, "h": 9, "text": "Finder", "w": 32, "x": 37, "y": 6},
      {"confidence": 1, "h": 93, "text": "PHANTOM", "w": 633, "x": 322, "y": 477}
    ],
    "scaledWidth": 1280,
    "scaledHeight": 717
  }
}

Source: README.md

This enables click-targeting of UI elements without consuming image tokens. The OCR operates on-device using Apple Vision framework with zero API cost and approximately 50ms latency. Source: LAUNCHGUIDE.md

Configuration

Screen-related timing parameters can be adjusted at runtime:

Configuration changes apply immediately without reconnection:

{"method": "configure", "params": {"cursor_crop_radius": 200}}

{"result": {"detail": "OK — changed: cursor_crop_radius"}}

Source: README_TR.md

Connection Reliability

During extended test sessions, VNC connections may drop, causing screen operations to fail. This is a known issue with VNC/ARD servers during long-running sessions (~50 turns). The SSH connection to the remote Mac typically remains active, indicating the issue is on the VNC server side rather than the daemon or network layer. Source: GitHub Issue #8

For CI/CD integration, consider implementing retry logic around screen capture operations. The daemon supports automatic reconnection unless --no-reconnect is specified. Source: README_TR.md

Tool Schema

Screen operations are defined in the MCP tool schema:

Source: tools/index.js

Architecture

graph TD
    subgraph MCP_Proxy["MCP Proxy (Node.js)"]
        Tools["Tools Interface"]
    end
    
    subgraph VNC_Daemon["VNC Daemon (Swift/C)"]
        CMD["CMD Handler"]
        Capture["Capture Module"]
        VNC["VNC Client"]
    end
    
    subgraph VNC_Server["VNC Server"]
        Framebuffer["Framebuffer<br/>:5900"]
        Desktop["Desktop Environment"]
    end
    
    Tools -->|"vnc_command"| CMD
    CMD --> Capture
    Capture -->|"RFB Protocol"| VNC
    VNC --> Framebuffer
    Framebuffer --> Desktop
    
    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 Tools proxy
    class CMD,Capture,VNC daemon
    class Framebuffer,Desktop target

The Capture module receives raw framebuffer updates from the VNC server and encodes them as PNG for transmission to the MCP proxy layer. Source: README.md

See Also

• Mouse Operations — Cursor movement and clicking
• Keyboard Operations — Key input and typing
• OCR Detection — Text element identification
• Configuration — Runtime parameter adjustment

Overview

Input Control in Claude KVM provides comprehensive mouse and keyboard automation capabilities for remote VNC desktop environments. The Swift daemon translates high-level MCP tool calls into RFB (Remote Framebuffer) protocol events, enabling precise interaction with remote desktops from AI agents. All coordinate-based actions operate within a scaled coordinate space that maps to the native framebuffer resolution, ensuring consistent behavior across different display configurations.

The input system supports seven mouse actions and four keyboard actions, each with configurable timing parameters that control press duration, inter-action delays, and settle times. This design allows the system to adapt to varying VNC server responsiveness and target application latency, which is particularly important for macOS targets using Apple Remote Desktop where timing-sensitive applications may require tuning.

Architecture

graph TD
    subgraph MCP_Proxy["MCP Proxy Layer"]
        Server["MCP Server<br/>JSON-RPC stdio"]
        Tools["Tools Handler"]
    end
    
    subgraph Daemon["VNC Daemon Layer"]
        CMD["Command Parser<br/>PC Protocol"]
        Mouse["Mouse Controller"]
        KB["Keyboard Controller"]
        Scale["Coordinate Scaler"]
    end
    
    subgraph VNC["VNC/RFB Layer"]
        VNC_Client["VNC Client<br/>RFB Protocol"]
    end
    
    Server -->|method + params| Tools
    Tools -->|vnc_command| CMD
    CMD -->|scaled coords| Scale
    Scale -->|native coords| Mouse
    Scale -->|native coords| KB
    Mouse -->|pointer events| VNC_Client
    KB -->|key events| VNC_Client
    
    classDef proxy fill:#1a1a2e,stroke:#16213e,color:#e5e5e5
    classDef daemon fill:#0f3460,stroke:#533483,color:#e5e5e5
    classDef vnc fill:#1a1a2e,stroke:#e94560,color:#e5e5e5
    
    class Server,Tools proxy
    class CMD,Mouse,KB,Scale daemon
    class VNC_Client vnc

The daemon receives commands via stdin using the PC (Procedure Call) protocol over NDJSON. Each command specifies an action type and parameters, which the command parser routes to the appropriate controller. The coordinate scaler transforms all XY coordinates from the scaled display space (default max 1280px) to the native framebuffer resolution before injection.

Source: tools/index.js:1-85

Mouse Control

Supported Actions

The mouse controller handles all pointer-based interactions through the VNC connection. Each action maps to specific RFB pointer events that the VNC server interprets and forwards to the desktop environment.

Source: tools/index.js:45-55

Coordinate System

Mouse coordinates operate in the scaled coordinate space, not native screen pixels. The daemon automatically scales coordinates based on the max_dimension parameter (default 1280px) and the actual VNC framebuffer dimensions.

Native:  4220 × 2568  (VNC server framebuffer)
Scaled:  1280 × 779   (what Claude targets)

mouse_click(640, 400) → Daemon scales to → VNC receives (2110, 1284)

Source: README.md:148-156

Drag Implementation

Mouse dragging implements interpolated movement between start and end points. The daemon breaks the drag path into discrete steps, pressing and releasing at appropriate intervals to ensure the target application receives motion events correctly.

Source: README.md:198-210

Scroll Behavior

Scroll actions generate wheel events with configurable tick parameters. The scroll operation moves the mouse cursor to the specified coordinates and then sends wheel events in the requested direction.

Source: README.md:213-216

Keyboard Control

Supported Actions

The keyboard controller translates text and key commands into VNC key events. It handles both individual key presses and complex modifier combinations required for macOS shortcuts.

Source: tools/index.js:56-60

Character-by-Character Typing

The key_type action sends each character individually rather than as a string, which ensures compatibility with applications that do not support direct string input. The daemon inserts configurable delays between keystrokes to account for input latency.

Source: README.md:222-225

Modifier Combinations

Modifier combinations support both string shortcuts ("cmd+c") and array syntax (["cmd","shift","3"]). The daemon handles Meta-to-Super key remapping for macOS targets, converting between Windows/Linux and macOS modifier key semantics automatically.

Source: README.md:217-220

Clipboard Paste

The paste action writes text to the system clipboard and then simulates the paste keyboard shortcut. This approach bypasses character encoding issues that can occur with direct keyboard input.

Source: README.md:226

Timing Configuration

Runtime Configuration

All timing parameters can be adjusted at runtime using the configure action without reconnecting to the VNC server. Current values are retrievable via the get_timing action.

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

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

Reset all parameters to defaults:

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

Source: README.md:183-197

Complete Parameter Reference

Source: README.md:198-226

Action Queue

The action_queue tool enables batching up to 20 sequential input actions in a single tool call. This reduces round-trip latency for multi-step workflows such as selecting text or navigating menus.

{
  "name": "action_queue",
  "description": "Batch up to 20 sequential VNC actions, returns text-only results",
  "inputSchema": {
    "queue": [
      {
        "action": "key_tap",
        "key": "cmd"
      },
      {
        "action": "key_type",
        "text": "hello world"
      }
    ]
  }
}

Source: tools/index.js:98-130

Known Limitations

VNC Connection Stability

During extended test sessions with high-frequency input operations, VNC connections may become unstable. The community has reported connection drops occurring after approximately 50 turns of interaction, though SSH connectivity to the remote Mac remains active. This indicates the issue originates in the VNC/ARD server layer rather than the daemon or network infrastructure.

Users experiencing this behavior should consider implementing periodic reconnection logic or monitoring connection health via the health action. The daemon provides connection status and display information through this action, allowing automated systems to detect and recover from degraded states.

Community Issue: VNC connection drops during long-running test sessions — VNC connections may drop during extended sessions with frequent input operations. SSH remains functional, confirming the issue is VNC/ARD server-side.

Timing Sensitivity on macOS

Applications with strict timing requirements may need parameter tuning. The default values are optimized for general desktop interaction but may not suit latency-sensitive operations. Adjust click_hold_ms and type_inter_key_ms to accommodate applications that require faster or slower input rates.

Tool Definitions

vnc_command Schema

{
  action: z.enum([
    'screenshot', 'cursor_crop', 'diff_check', 'set_baseline',
    'mouse_click', 'mouse_double_click', 'mouse_move', 'hover', 'nudge',
    'mouse_drag', 'scroll',
    'key_tap', 'key_combo', 'key_type', 'paste',
    'detect_elements',
    'configure', 'get_timing',
    'wait', 'health', 'shutdown',
  ]),
  x: z.number().int().min(0).max(width - 1).optional(),
  y: z.number().int().min(0).max(height - 1).optional(),
  toX: z.number().int().min(0).max(width - 1).optional(),
  toY: z.number().int().min(0).max(height - 1).optional(),
  dx: z.number().int().min(-50).max(50).optional(),
  dy: z.number().int().min(-50).max(50).optional(),
  direction: z.enum(['up', 'down', 'left', 'right']).optional(),
  amount: z.number().int().min(1).max(200).optional(),
  key: z.string().optional(),
  keys: z.array(z.string()).optional(),
  text: z.string().optional(),
  button: z.enum(['left', 'right', 'middle']).optional(),
}

Source: tools/index.js:42-85

Usage Examples

Basic Mouse Click

{"method":"vnc_command","params":{"action":"mouse_click","x":640,"y":400}}

Drag Operation

{"method":"vnc_command","params":{"action":"mouse_drag","x":100,"y":200,"toX":400,"toY":300}}

Keyboard Shortcut

{"method":"vnc_command","params":{"action":"key_combo","keys":["cmd","shift","3"]}}

Type Text

{"method":"vnc_command","params":{"action":"key_type","text":"Hello, World!"}}

Source: README.md:160-179

Related Documentation

• Server Configuration — Environment variables and setup
• Package Information — MCP server metadata
• Launch Guide — Initial setup and daemon installation

Related Pages

Related topics: Screen Operations

OCR Detection

Overview

OCR Detection (detect_elements) is a core capability of the claude-kvm tool that performs on-device text recognition using Apple's Vision framework. It scans the current screen state and returns all detected text elements with their bounding box coordinates in the scaled coordinate space used by the VNC session.

Key characteristics:

• On-device processing — Uses Apple Vision framework directly on the remote Mac, eliminating API costs and network latency
• Bounding box coordinates — Returns precise x, y, width, and height for each detected element
• Scaled coordinate space — All coordinates match the scaled display dimensions, enabling direct use with mouse actions
• Fast performance — Approximately 50ms per detection operation
• Confidence scoring — Each detected element includes a confidence value

Source: README_TR.md

Architecture

graph TD
    A[Claude Agent] -->|vnc_command<br/>detect_elements| B[MCP Proxy<br/>index.js]
    B -->|NDJSON PC Protocol| C[VNC Daemon<br/>claude-kvm-daemon]
    C -->|Apple Vision Framework| D[Remote macOS Screen]
    D -->|VNCScreenshot| C
    C -->|OCR Results| B
    B -->|JSON Response| A

The OCR Detection feature operates within the broader VNC daemon architecture:

Source: README.md

Tool Definition

The detect_elements action is defined as part of the vnc_command tool schema:

action: z.enum([
  'screenshot', 'cursor_crop', 'diff_check', 'set_baseline',
  'mouse_click', 'mouse_double_click', 'mouse_move', 'hover', 'nudge',
  'mouse_drag', 'scroll',
  'key_tap', 'key_combo', 'key_type', 'paste',
  'detect_elements',  // <-- OCR action
  'configure', 'get_timing',
  'wait', 'health', 'shutdown',
]).describe('The action to perform'),

Source: tools/index.js

API Reference

Request

{
  "method": "vnc_command",
  "params": {
    "action": "detect_elements"
  }
}

Response

Element Object

Example Response

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

Source: README_TR.md

Coordinate System

All bounding box coordinates returned by detect_elements are in the scaled coordinate space. This means:

1. The VNC server's native resolution is scaled down to fit within --max-dimension (default: 1280px)
2. The coordinates can be used directly with mouse actions without conversion
3. The scaledWidth and scaledHeight fields indicate the current display dimensions

Native:  4220 x 2568  (VNC server framebuffer)
Scaled:  1280 x 779   (what detect_elements returns)

Source: README.md

Usage Patterns

Basic Text Detection

1. Take screenshot to verify current state
2. Run detect_elements to find all text
3. Identify target element by text content
4. Use bounding box coordinates for mouse_click

Workflow Integration

The detect_elements action fits into the standard interaction pattern:

Precise Click Targeting

Instead of guessing click positions, use detect_elements to locate buttons or text by their content:

// After detect_elements returns:
// {"text": "Submit", "x": 450, "y": 320, "w": 80, "h": 30}

// Click center of the element:
mouse_click(490, 335)  // x + w/2, y + h/2

Performance Characteristics

Limitations and Considerations

VNC Session Stability

During long-running test sessions with many operations, VNC connections may drop. This is a known issue with the VNC/ARD server side, not the OCR feature itself:

During extended test sessions (~50 turns), the VNC connection drops and the daemon becomes unresponsive. SSH to the remote Mac remains active, confirming the issue is on the VNC/ARD server side — not the daemon or network layer.

Source: Issue #8

Mitigation strategies:

• Implement reconnection logic in automation scripts
• Use --no-reconnect flag and handle reconnection manually
• Consider restarting the VNC server if drops occur frequently

Confidence Values

Not all elements return confidence: 1. Lower confidence values indicate uncertain recognition. Consider adding validation logic for critical UI elements:

// Filter high-confidence elements only
const reliableElements = result.elements.filter(el => el.confidence >= 0.9);

Scaling Dependencies

OCR results are tied to the current display scaling. If --max-dimension changes, bounding box coordinates will differ. Always use coordinates from the same session's detection.

Configuration

The OCR feature itself has no separate configuration, but display scaling affects results:

{
  "env": {
    "CLAUDE_KVM_DAEMON_PARAMETERS": "--max-dimension 960"
  }
}

Source: server.json

See Also

• Mouse Actions — Using coordinates returned by detect_elements
• Screenshot Actions — Capturing screen state before detection
• Configuration — Runtime timing and display parameters

Related Pages

Related topics: Quick Start Guide, Environment Variables

Authentication Methods

Claude KVM supports two primary VNC authentication mechanisms for remote desktop control: VNC Auth (standard challenge-response) and Apple Remote Desktop (ARD) authentication. The daemon automatically detects and negotiates the appropriate authentication method based on the VNC server's capabilities.

Overview

The authentication layer sits between the MCP proxy (JavaScript/Node.js) and the native VNC daemon (Swift/C). When establishing a remote desktop connection, the daemon performs protocol negotiation with the VNC server to determine which authentication method to use.

graph TD
    subgraph Client_Side
        MCP[MCP Proxy<br/>JavaScript]
        CREDS[Credentials<br/>from Environment]
    end
    
    subgraph Daemon_Side
        DAEMON[claude-kvm-daemon<br/>Swift/C]
        LIBVNC[LibVNC<br/>Core]
    end
    
    subgraph Remote_Server
        VNC_SERVER[VNC Server<br/>macOS]
    end
    
    MCP -->|spawn process| DAEMON
    CREDS -->|VNC_USERNAME<br/>VNC_PASSWORD| MCP
    MCP -->|forward via stdin| DAEMON
    DAEMON -->|RFB Protocol| VNC_SERVER
    VNC_SERVER -->|auth challenge| DAEMON
    
    style VNC_SERVER fill:#f96
    style DAEMON fill:#bbf
    style MCP fill:#bfb

Source: index.js:1-30, README.md

Supported Authentication Types

VNC Auth (Standard)

VNC Auth is the traditional password-based authentication method used by most VNC servers. It implements a challenge-response protocol using the DES cipher.

The authentication flow for VNC Auth:

1. Client connects to VNC server
2. Server sends a 16-byte random challenge
3. Client encrypts challenge using password as DES key
4. Client sends 16-byte response
5. Server validates response against stored password

Source: README.md

Apple Remote Desktop (ARD)

ARD authentication is a proprietary macOS authentication method that provides enhanced security through cryptographic key exchange and symmetric encryption.

The authentication flow for ARD:

1. Client initiates connection with ARD auth type request
2. Server responds with Diffie-Hellman parameters
3. Client and server perform key exchange
4. Client encrypts credentials using derived session key (AES-128-ECB)
5. Server decrypts and validates credentials

Source: README.md

Auto-Detection Mechanism

The daemon automatically detects whether the remote VNC server is a standard VNC server or an Apple Remote Desktop server. This detection occurs during the RFB protocol handshake phase.

sequenceDiagram
    participant C as MCP Proxy
    participant D as claude-kvm-daemon
    participant S as VNC Server
    
    C->>D: Spawn daemon process
    D->>S: TCP Connection
    S-->>D: Server Protocol Version
    D->>S: Client Protocol Version
    S-->>D: Security Types List
    Note over D: Checks for auth type 30<br/>(ARD)
    alt ARD Detected
        Note over D: Use DH key exchange<br/>+ AES-128-ECB
        D->>S: Auth Type 30 Request
        S-->>D: DH Parameters
        D->>S: DH Public Key
        S-->>D: DH Public Key + AES Encrypted Creds
    else Standard VNC
        Note over D: Use DES Challenge-Response
        D->>S: Auth Type 2 Request
        S-->>D: 16-byte Challenge
        D->>S: 16-byte Response
    end
    S-->>D: Auth Result

The auto-detection is triggered by observing the auth type 30 credential request from the server, which is specific to macOS ARD implementations.

Source: README.md

Credential Configuration

Environment Variables

Authentication credentials are passed to the daemon through environment variables configured in the .mcp.json file.

Example .mcp.json configuration:

{
  "mcpServers": {
    "claude-kvm": {
      "command": "npx",
      "args": ["-y", "claude-kvm"],
      "env": {
        "VNC_HOST": "192.168.1.100",
        "VNC_PORT": "5900",
        "VNC_USERNAME": "admin",
        "VNC_PASSWORD": "secretpassword"
      }
    }
  }
}

Source: server.json, README.md

Username Requirements

For ARD servers, the VNC_USERNAME environment variable is mandatory. The daemon passes both username and password to the authentication handler when auth type 30 is detected.

Source: README.md

Key Remapping for macOS Targets

When connecting to macOS systems via ARD authentication, a Meta-to-Super key remapping occurs automatically. This ensures keyboard compatibility between the MCP client and the macOS target.

This remapping is applied specifically when the daemon detects the ARD auth type 30 credential request, indicating a macOS target. The remapping ensures that keyboard shortcuts (e.g., ⌘+C for copy) work correctly from remote clients.

Source: README.md

Connection Parameters

Daemon CLI Parameters

Authentication-related connection parameters can be configured via the CLAUDE_KVM_DAEMON_PARAMETERS environment variable:

Example with authentication parameters:

{
  "env": {
    "CLAUDE_KVM_DAEMON_PARAMETERS": "--connect-timeout 30 --no-reconnect"
  }
}

Source: README.md, README_TR.md

Timeout Behavior

The --connect-timeout parameter affects how long the daemon waits during the authentication handshake. If authentication is slow (common with ARD's Diffie-Hellman exchange), the timeout should be set appropriately:

Health Check and Connection Status

The health action provides connection status including authentication state:

{"method":"health"}

Response includes:

• Connection status
• Display information
• Authentication method in use

This allows verifying successful authentication before attempting remote control operations.

Source: tools/index.js

Protocol Communication

The MCP proxy communicates with the daemon using the PC (Procedure Call) protocol over stdin/stdout NDJSON. Authentication-related requests flow through this channel.

The daemon handles all authentication internally; the proxy only receives success/failure notifications and connection state updates.

Source: index.js:1-30, README.md

Security Considerations

Network Security

Credential Storage

macOS VNC Security

For bare-metal Mac connections, consider enabling SSH tunneling to add an additional layer of security. The Mac M1 Preparation Tricks guide covers VNC security, SSH tunneling, and session stability configurations.

Source: README.md

Troubleshooting Authentication Issues

Common Issues

Debug Authentication

Enable verbose logging to see authentication handshake details:

VNC_HOST=192.168.1.100 \
VNC_PASSWORD=secret \
CLAUDE_KVM_DAEMON_PARAMETERS="-v" \
npx -y claude-kvm

Verbose output will show:

• Security types offered by server
• Authentication method selected
• Key exchange progress (ARD)
• Challenge/response exchange (VNC Auth)

Source: README.md

Summary

The daemon's automatic detection and negotiation capabilities allow seamless connections to both standard VNC servers and macOS ARD servers without manual authentication method selection.

Source: README.md, server.json

Related Pages

Related topics: Installation Guide

Environment Variables

This page documents all environment variables used by the claude-kvm MCP server for VNC connection configuration and daemon operation.

Overview

Environment variables in claude-kvm serve as the primary configuration mechanism for establishing and maintaining VNC connections to remote desktops. These variables control connection parameters, authentication credentials, and daemon execution paths. The MCP server reads these variables at startup and uses them to configure the underlying VNC daemon process.

graph TD
    A[Claude Code] -->|stdio JSON-RPC| B[MCP Proxy<br/>Node.js]
    B -->|Reads Env Vars| C[VNC_HOST<br/>VNC_PORT<br/>VNC_USERNAME<br/>VNC_PASSWORD]
    B -->|Spawns Daemon| D[claude-kvm-daemon]
    D -->|VNC Protocol| E[Remote Desktop]
    
    C -->|Credential Injection| D

The environment variables are defined in the MCP server manifest (server.json) and validated against the Zod schema in the proxy layer. Source: server.json

Required Variables

These variables must be set for the MCP server to establish a VNC connection.

VNC_HOST

Specifies the hostname or IP address of the remote VNC server to connect to.

VNC_HOST="192.168.1.100"
VNC_HOST="vnc.example.com"
VNC_HOST="10.0.0.50"

Constraints:

• Must be a valid hostname or IPv4/IPv6 address
• Must be reachable from the machine running the MCP server
• Connection validation occurs when the daemon attempts to connect

Source: server.json

VNC_PORT

Specifies the TCP port number on which the VNC server is listening.

VNC_PORT="5900"    # Default VNC port
VNC_PORT="5901"    # Display :1
VNC_PORT="mac"     # For macOS Screen Sharing (varies)

Common Port Values:

• 5900 - Default VNC port (display :0)
• 5901 - Display :1
• 5902 - Display :2
• Screen Sharing on macOS typically uses port 5900

Source: server.json

Optional Variables

These variables enhance functionality or are required for specific VNC server configurations.

VNC_USERNAME

The username for authenticating with the VNC server. This is required when using Apple Remote Desktop (ARD) authentication.

VNC_USERNAME="admin"
VNC_USERNAME="remoteuser"

Use Cases:

• Apple Remote Desktop (ARD) authentication
• VNC servers with username/password authentication
• Enterprise VNC configurations

Source: server.json

VNC_PASSWORD

The password for authenticating with the VNC server. This value is marked as a secret and should never be committed to version control.

VNC_PASSWORD="secure_password_here"

Security Considerations:

• Store in environment files that are excluded from version control
• Consider using secret management tools (e.g., 1Password, HashiCorp Vault)
• Never log or display this value in error messages

Source: server.json

CLAUDE_KVM_DAEMON_PATH

Specifies the absolute filesystem path to the claude-kvm-daemon executable. When not specified, the MCP proxy attempts to locate the daemon in the system PATH.

# Homebrew installation (Apple Silicon)
CLAUDE_KVM_DAEMON_PATH="/opt/homebrew/bin/claude-kvm-daemon"

# Homebrew installation (Intel)
CLAUDE_KVM_DAEMON_PATH="/usr/local/bin/claude-kvm-daemon"

# Custom installation
CLAUDE_KVM_DAEMON_PATH="/usr/local/bin/claude-kvm-daemon"

Installation Methods:

• Homebrew tap: brew install claude-kvm-daemon
• Manual: Download from releases and install to desired location

Source: README.md

Configuration Methods

claude-kvm supports multiple methods for setting environment variables depending on your deployment scenario.

MCP Configuration File

The recommended approach for Claude Code desktop applications uses a .mcp.json configuration file in the project directory:

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

Source: README.md

Shell Environment

For CLI usage or testing, export variables in the shell:

export VNC_HOST="192.168.1.100"
export VNC_PORT="5900"
export VNC_USERNAME="admin"
export VNC_PASSWORD="secret"
export CLAUDE_KVM_DAEMON_PATH="/opt/homebrew/bin/claude-kvm-daemon"

npx claude-kvm

Environment File (.env)

Create a .env file (ensure it's in .gitignore):

VNC_HOST=192.168.1.100
VNC_PORT=5900
VNC_USERNAME=admin
VNC_PASSWORD=secret
CLAUDE_KVM_DAEMON_PATH=/opt/homebrew/bin/claude-kvm-daemon

Then load it in your shell:

source .env
npx claude-kvm

Authentication Methods

The environment variables interact with two supported VNC authentication mechanisms.

VNC Authentication

Standard VNC password-based challenge-response using DES encryption:

VNC_HOST="vnc.example.com"
VNC_PORT="5900"
VNC_PASSWORD="vnc_password"

Apple Remote Desktop (ARD)

For macOS targets, ARD uses Diffie-Hellman key exchange with AES-128-ECB encryption. The username is required:

VNC_HOST="mac-mini.local"
VNC_PORT="5900"
VNC_USERNAME="admin"
VNC_PASSWORD="ard_password"

macOS Detection: The daemon automatically detects ARD servers by the auth type 30 credential request and applies Meta-to-Super key remapping for Command key compatibility. Source: README.md

Runtime Configuration

While environment variables set initial configuration, the running daemon supports runtime parameter adjustments through the configure action:

{
  "action": "configure",
  "params": {
    "max_dimension": 1280,
    "click_hold_ms": 80,
    "key_hold_ms": 50
  }
}

Timing Parameters:

Source: README.md

Security Best Practices

Credential Management

1. Never commit credentials - Add .env and .mcp.json to .gitignore
2. Use secret managers - Integrate with 1Password, AWS Secrets Manager, or similar
3. Rotate passwords - Update VNC passwords regularly
4. Limit access - Ensure only necessary users can read configuration

Network Security

For remote VNC connections over untrusted networks:

1. Use SSH tunneling - Tunnel VNC traffic through SSH
2. Enable encryption - Configure VNC server with TLS/SSL
3. Restrict access - Use firewall rules to limit VNC server exposure

Daemon Path Security

• Verify the daemon binary is owned by root and not writable by other users
• Use absolute paths to prevent PATH hijacking
• On macOS, ensure the daemon is code-signed and notarized

Troubleshooting

Connection Issues

Problem: VNC connection drops during long-running test sessions

This is a known issue (#8) related to VNC/ARD server stability, not the daemon or network layer. Workarounds:

• Use the --no-reconnect flag to control reconnection behavior
• Implement application-level retry logic
• Consider SSH tunneling for more stable connections

Source: GitHub Issue #8

Variable Validation

The MCP proxy validates environment variables against the schema defined in server.json. Invalid values result in startup errors with descriptive messages.

Daemon Path Issues

If the daemon cannot be found:

1. Verify the path exists: ls -la /opt/homebrew/bin/claude-kvm-daemon
2. Check PATH: which claude-kvm-daemon
3. Explicitly set CLAUDE_KVM_DAEMON_PATH

Summary

For most use cases, only VNC_HOST and VNC_PORT are required. Add VNC_USERNAME and VNC_PASSWORD when connecting to authenticated VNC servers or macOS with Screen Sharing enabled.

Doramagic Pitfall Log

Found 8 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | cevd_c5f8215134dd43ca8306d08dc0e808ac | https://github.com/ARAS-Workspace/claude-kvm/issues/8

2. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | mcp_registry:io.github.ARAS-Workspace/claude-kvm:2.0.11 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.ARAS-Workspace%2Fclaude-kvm/versions/2.0.11

3. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | mcp_registry:io.github.ARAS-Workspace/claude-kvm:2.0.11 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.ARAS-Workspace%2Fclaude-kvm/versions/2.0.11

4. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | mcp_registry:io.github.ARAS-Workspace/claude-kvm:2.0.11 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.ARAS-Workspace%2Fclaude-kvm/versions/2.0.11

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | mcp_registry:io.github.ARAS-Workspace/claude-kvm:2.0.11 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.ARAS-Workspace%2Fclaude-kvm/versions/2.0.11

6. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | mcp_registry:io.github.ARAS-Workspace/claude-kvm:2.0.11 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.ARAS-Workspace%2Fclaude-kvm/versions/2.0.11

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | mcp_registry:io.github.ARAS-Workspace/claude-kvm:2.0.11 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.ARAS-Workspace%2Fclaude-kvm/versions/2.0.11

8. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | mcp_registry:io.github.ARAS-Workspace/claude-kvm:2.0.11 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.ARAS-Workspace%2Fclaude-kvm/versions/2.0.11

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using claude-kvm with real data or production workflows.

• VNC connection drops during long-running test sessions - github / github_issue
• claude-kvm-daemon 1.0.1 - github / github_release
• claude-kvm-daemon 1.0.0 - github / github_release
• Configuration risk requires verification - GitHub / issue