Claude Code KVM — Claude Code MCP server for VNC desktops
Claude KVM lets an agent inspect and control a remote desktop over VNC. Use it for tasks that require interacting with a graphical interface.
claude mcp add claude-kvm -e VNC_HOST=<VNC_HOST> -e VNC_PORT=<VNC_PORT> -e VNC_USERNAME=<VNC_USERNAME> -e VNC_PASSWORD=<VNC_PASSWORD> -e CLAUDE_KVM_DAEMON_PATH=<CLAUDE_KVM_DAEMON_PATH> -- npx -y claude-kvmWhat Claude KVM does
Claude KVM connects an MCP client to a remote machine over VNC. A JavaScript proxy launches a native daemon written in Swift and C; the daemon captures the screen and sends mouse and keyboard input. Apple Vision handles OCR, and the daemon maps clicks from the scaled image to the VNC server’s native resolution.
An agent can locate interface elements, read on-screen text, and click buttons. Setup requires macOS on Apple Silicon, Node.js LTS, a reachable VNC server, and values for VNC_HOST, VNC_PORT, VNC_USERNAME, VNC_PASSWORD, and CLAUDE_KVM_DAEMON_PATH. Without a working VNC connection, the agent has no desktop to control.
What it helps with
- click a control in a remote desktop app
- read screen text with OCR
- enter text into a remote application
- drag an item across the desktop
Example prompts for the agent
- Find the save button on the remote screen and click it.
- Read the text in the window, then enter it in the search field.
- Move the file into a folder on the remote desktop by dragging it.
How to install Claude KVM
Platform CLI
claude mcp add claude-kvm -e VNC_HOST=<VNC_HOST> -e VNC_PORT=<VNC_PORT> -e VNC_USERNAME=<VNC_USERNAME> -e VNC_PASSWORD=<VNC_PASSWORD> -e CLAUDE_KVM_DAEMON_PATH=<CLAUDE_KVM_DAEMON_PATH> -- npx -y claude-kvmReplace <…> with your own values
Platform CLI
codex mcp add claude-kvm --env VNC_HOST=<VNC_HOST> --env VNC_PORT=<VNC_PORT> --env VNC_USERNAME=<VNC_USERNAME> --env VNC_PASSWORD=<VNC_PASSWORD> --env CLAUDE_KVM_DAEMON_PATH=<CLAUDE_KVM_DAEMON_PATH> -- npx -y claude-kvmReplace <…> with your own values
Config file
{
"mcpServers": {
"claude-kvm": {
"command": "npx",
"args": [
"-y",
"claude-kvm"
],
"env": {
"VNC_HOST": "<VNC_HOST>",
"VNC_PORT": "<VNC_PORT>",
"VNC_USERNAME": "<VNC_USERNAME>",
"VNC_PASSWORD": "<VNC_PASSWORD>",
"CLAUDE_KVM_DAEMON_PATH": "<CLAUDE_KVM_DAEMON_PATH>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"claude-kvm": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"claude-kvm"
],
"env": {
"VNC_HOST": "<VNC_HOST>",
"VNC_PORT": "<VNC_PORT>",
"VNC_USERNAME": "<VNC_USERNAME>",
"VNC_PASSWORD": "<VNC_PASSWORD>",
"CLAUDE_KVM_DAEMON_PATH": "<CLAUDE_KVM_DAEMON_PATH>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e VNC_HOST=<VNC_HOST> -e VNC_PORT=<VNC_PORT> -e VNC_USERNAME=<VNC_USERNAME> -e VNC_PASSWORD=<VNC_PASSWORD> -e CLAUDE_KVM_DAEMON_PATH=<CLAUDE_KVM_DAEMON_PATH> claude-kvm npx -y claude-kvmReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Claude KVM
How do I install Claude KVM in Codex?
Add the server with `codex mcp add claude-kvm --env VNC_HOST=<VNC_HOST> --env VNC_PORT=<VNC_PORT> --env VNC_USERNAME=<VNC_USERNAME> --env VNC_PASSWORD=<VNC_PASSWORD> --env CLAUDE_KVM_DAEMON_PATH=<CLAUDE_KVM_DAEMON_PATH> -- npx -y claude-kvm`. You also need macOS on Apple Silicon, Node.js LTS, and access to a VNC server.
What does Claude KVM do?
It connects an agent to a remote desktop over VNC. The agent can inspect screen images, recognize text, and send mouse or keyboard actions.
How does Claude KVM read text on screen?
It uses Apple Vision for OCR and returns recognized text with coordinates mapped to the scaled screen image.
