Claude KVM

- Capture and inspect the remote screen— Request a fullscreenshotor acursor_croparound the mouse pointer to see the current desktop state.
- Detect on-screen text and UI elements— Rundetect_elementsto get OCR text with bounding-box coordinates, enabling precise click targeting without consuming vision tokens.
- Control the mouse and keyboard remotely— Executemouse_click,mouse_drag,key_type,key_combo, orpasteto interact with applications on the target machine.
- Check for visual changes efficiently— Usediff_checkto detect whether the screen has changed from a savedset_baseline, avoiding unnecessary full image transfers.
- Adjust timing and display scaling at runtime— Callconfigureto tune click-hold delays, drag interpolation, ormax_dimensionfor different VNC environments.

Claude KVM is an MCP tool that controls remote desktop environments over VNC. It consists of a thin JS proxy layer (MCP server) and a platform-native Swift VNC daemon running on your macOS system.

[!TIP]Phantom-WGcould be a great alternative for you.Isolate your VNC server within your own network while enjoying self-hosted VPN performance with the extra privacy features you gain along the way.

- Integration Test
- Mac Integration Test
- Mac Calculator Test
- Mac Scientific Calculator Test
- Mac Safari Browsing Test
- Mac Drag & Drop Test
- Mac Chess Test
- Mac Chess Direct Test
- Mac Phantom-WG Install Test

[!NOTE] Tests are conducted transparently on GitHub Actions — each step is visible in the CI environment. At the end of every test, whether the integration passes or fails, you'll find screenshots of each step the agent took during the session, along with an.mp4video recording that captures the entire session. By reviewing these recordings and screenshots, you can observe how the agent progressed through each stage, how long the task took, and what decisions were made based on the system prompt. You can use these examples as a reference when crafting your own system prompts or instructions for the MCP server in your own environment.

[!WARNING] Artifacts attached to these runs may have expired due to GitHub's artifact retention policy. Persistent copies are prepared via thePersist Artifactsworkflow and can always be accessed by run ID from theartifacts/directory on the press-kit branch.

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

Communication between the proxy and daemon uses the PC protocol over 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":{...}}

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:

Native: 4220 x 2568 (VNC server framebuffer) Scaled: 1280 x 779 (what Claude sees and targets) mouse_click(640, 400) → VNC receives (2110, 1284)

Claude minimizes token cost with a progressive verification approach:

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_elementsuses Apple Vision framework for on-device OCR. Returns text content with bounding box coordinates in scaled space — enables precise click targeting without consuming vision tokens.

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

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

[!NOTE]claude-kvm-daemonis compiled and code-signed via CI (GitHub Actions). The build output is packaged in two formats: a.tar.gzarchive for Homebrew distribution and a.dmgdisk image for notarization. The DMG is submitted to Apple servers for notarization within the same workflow — the process can be tracked from CI logs. The notarized DMG is available as a CI Artifact; the archived.tar.gzis also published as a release on the repository. Homebrew installation tracks this release.

- Release·Source Code
- LibVNC Build·LibVNC Branch
- Homebrew Tap

{ "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] The tool is end-to-end tested via CI — Claude executes tasks over VNC while an independent vision model observes and verifies the results. See theIntegration Testfor live workflow runs, system prompts, and demo recordings.

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

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

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

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

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

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

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

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

- VNC Auth— password-based challenge-response (DES)
- ARD— Apple Remote Desktop (Diffie-Hellman + AES-128-ECB)

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

[!NOTE] Running on a bare-metal Mac? See theMac M1 Preparation Tricksfor VNC hardening, SSH tunneling, and session stability tips.

AI-native network automation for MikroTik RouterOS. MikroMCP exposes RouterOS as a typed, auditable Model Context Protocol server so Claude, Cursor, Codex, and other MCP clients can inspect, diagnose, and safely operate MikroTik routers in natural language.