Claude KVM

Claude KVM MCP Server enables you to manage remote desktop environments over VNC through a lightweight MCP proxy and a native VNC daemon on macOS. It provides a configurable bridge between an AI agent and a target macOS or other VNC-enabled machines, enabling automated control of the desktop via MCP commands.

How to use

You connect to the Claude KVM MCP Server using an MCP client. The MCP proxy talks to the Claude KVM daemon on your machine, which in turn interfaces with a VNC server on the target device. You configure display scaling and timing parameters at runtime to optimize interaction for your environment. Typical workflows include taking screen captures, performing OCR-driven element detection, simulating mouse and keyboard input, and adjusting display scale to balance performance and accuracy.

How to install

Prerequisites: you need a macOS system (Apple Silicon / aarch64) and Node.js LTS installed.

# Install the native VNC daemon via Homebrew
brew tap ARAS-Workspace/tap
brew install claude-kvm-daemon

# Create an MCP configuration in your project directory
cat > .mcp.json << 'JSON'
{
  "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"
      }
    }
  }
}
JSON

# Start the MCP server through your MCP client by loading this config

Configuration and runtime tuning

The server exposes runtime configuration for timing and display parameters. You can set these at runtime using the configure method, inspect current values with get_timing, and reset to defaults when needed.

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

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

{"method":"get_timing"}

{"result":{"timing":{"click_hold_ms":80,"max_dimension":1280},"scaledWidth":1280,"scaledHeight":779}}

Security and access notes

You control the VNC connection details through environment variables in the MCP configuration. Treat VNC credentials as sensitive information and restrict access to the MCP client and the machine running the Claude KVM daemon.

Troubleshooting tips

If the daemon cannot establish a VNC connection, verify the VNC host, port, username, and password. Ensure the CLAUDE_KVM_DAEMON_PATH points to the correct binary and that all required environment variables are set in the MCP configuration.

Notes

The MCP configuration shown uses a local npx invocation to start the claude-kvm MCP server with environment variables that define the VNC connection and the daemon path. You can adapt VNC_HOST, VNC_PORT, VNC_USERNAME, and VNC_PASSWORD to your target environment.

Additional sections

This MCP server supports a range of interactive tools to control the remote desktop, including screen capture, element detection via OCR, and input injection for mouse and keyboard actions. You can fine-tune timing and display parameters at runtime to optimize performance for your setup.

Tools and capabilities overview

The server exposes a set of operations to: capture the screen, crop around the cursor, detect elements via OCR, simulate mouse actions (clicks, moves, drags, scrolling), simulate keyboard input (key taps, key combos, typing, pasting), and manage runtime configuration. You can query current timing and display parameters and reset them to defaults as needed.

Available tools

screenshot

Full screen PNG capture of the current desktop view.

cursor_crop

Crop an image around the cursor with a crosshair overlay to assist precise clicking.

diff_check

Detect changes against a baseline image to determine if the screen has updated.

set_baseline

Save the current screen as the baseline for future difference checks.

mouse_click

Simulate a mouse click at specified coordinates with an optional button parameter.

mouse_double_click

Perform a rapid double click at the given coordinates.

mouse_move

Move the cursor to the specified coordinates.

hover

Move the cursor to coordinates and wait for a settle period.

nudge

Move the cursor by a relative delta.

mouse_drag

Drag from a start point to an end point.

scroll

Scroll in a direction with optional amount at a point.

key_tap

Press a single key.

key_combo

Press a key combination or sequence of keys.

key_type

Type text character by character.

paste

Paste text via clipboard injection.

detect_elements

OCR-based text detection with bounding boxes (Apple Vision).