mcp-kvm

The only AI that can fix a crashed computer, not just use one.

An MCP (Model Context Protocol) server that lets Claude, Cursor, or any MCP-compatible AI client control any computer through KVM hardware — including BIOS/UEFI, remote power on/off, login screens, blue screens, and locked machines. When Anthropic's Computer Use or OpenAI's Operator hit a locked screen and give up, mcp-kvm keeps working.

Status: Alpha (v0.1) — software, BliKVM, and PiKVM adapters all functional. 13 MCP tools including screenshot, mouse, keyboard, and ATX power control.

Why KVM instead of a software agent?

| Scenario | Software agents (Computer Use, Operator, UFO) | mcp-kvm | |----------|----------------------------------------------|-----------| | Automate a logged-in desktop | ✅ | ✅ | | Log in to a locked Windows machine | ❌ | ✅ | | Fix a blue screen or boot loop | ❌ | ✅ | | Control BIOS / UEFI settings | ❌ | ✅ | | Work on a machine where you can't install software | ❌ | ✅ | | Operate industrial / POS / embedded systems | ❌ | ✅ | | Handle air-gapped or compliance-restricted environments | ❌ | ✅ |

KVM (keyboard-video-mouse) hardware sits between your keyboard/mouse/monitor and the target computer. It's a physical layer — the target sees it as a normal USB keyboard and mouse, with zero software installed.

Quick Start

1. Install

# Easiest — one-line setup (auto-installs Python package, writes MCP config)
npx mcp-kvm init

# Or install Python package directly
pip install mcp-kvm[software]      # for controlling this machine
pip install mcp-kvm[blikvm]        # for BliKVM hardware
pip install mcp-kvm[pikvm]         # for PiKVM hardware
pip install mcp-kvm[all]           # all adapters

2. Configure your MCP client

After npx mcp-kvm init, a .mcp.json is written to your current directory (for Claude Code / Cursor). For Claude Desktop, add to claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-kvm": {
      "command": "uvx",
      "args": ["mcp-kvm-server"],
      "env": {
        "MCP_KVM_ADAPTER": "software"
      }
    }
  }
}

3. Restart your AI client and ask

"Take a screenshot and tell me what's on my screen."

"Open the Start menu and launch Notepad, then type 'Hello from Claude'."

The AI now has 13 tools: take_screenshot, get_screen_size, mouse_click, mouse_move, mouse_scroll, type_text, send_key, send_shortcut, power_on, power_off, reboot, get_power_state, adapter_info.

Adapters

mcp-kvm is adapter-based — the same MCP tools work across different backends. Set MCP_KVM_ADAPTER in your client config to switch.

software (default)

Uses pyautogui to control the same machine the server runs on. Good for:

• Quick local testing
• Single-machine automation
• Running on a Pi/NAS with an attached display

"env": { "MCP_KVM_ADAPTER": "software" }

blikvm (hardware)

Controls a remote machine via BliKVM v4. Full support: screenshot, mouse, keyboard, ATX power on/off/reboot.

"env": {
  "MCP_KVM_ADAPTER": "blikvm",
  "KVM_HOST": "192.168.1.100",
  "KVM_USER": "admin",
  "KVM_PASSWORD": "..."
}

pikvm (hardware, community-tested)

Controls a remote machine via PiKVM. Implements full API support based on official PiKVM documentation. Not yet verified on real hardware — community testing and feedback welcome via GitHub Issues.

"env": {
  "MCP_KVM_ADAPTER": "pikvm",
  "KVM_HOST": "192.168.1.100",
  "KVM_USER": "admin",
  "KVM_PASSWORD": "..."
}

Write your own

Subclass mcp_kvm.adapters.base.KVMAdapter and register via entry points. See docs/adapters/custom.md.

Remote Access (from outside your LAN)

mcp-kvm connects directly to your KVM device on the local network. To control machines while traveling, you need a way to reach your home/office network. The recommended approach is a mesh VPN — no port forwarding, no cloud relay, end-to-end encrypted.

Tailscale (recommended — 5 minutes to set up)

1. Install Tailscale on your laptop/phone and on the machine running mcp-kvm-server (or on the KVM device itself if it supports it — PiKVM has a Tailscale plugin).
2. Both devices join the same Tailnet.
3. Use the Tailscale IP in your MCP config:

"env": {
  "MCP_KVM_ADAPTER": "blikvm",
  "KVM_HOST": "100.64.0.5"
}

Now Claude Desktop on your laptop can reach the BliKVM at home, anywhere in the world. Tailscale's free tier supports up to 100 devices.

Other VPN options

| Option | Complexity | Notes | |--------|-----------|-------| | Tailscale | Easy | Free, peer-to-peer, recommended | | ZeroTier | Easy | Similar to Tailscale, self-hostable | | WireGuard | Medium | Manual config, fastest raw performance | | Cloudflare Tunnel | Medium | Good if you already use Cloudflare | | SSH tunnel | Advanced | ssh -L 8080:blikvm:80 your-server |

Tip: Most homelab and sysadmin users already run Tailscale or WireGuard — mcp-kvm slots right into your existing setup.

Security

• mcp-kvm runs entirely on your machine — no cloud, no data upload.
• Screenshots and inputs never leave the MCP protocol stream to your AI client.
• The software adapter intentionally disables pyautogui's failsafe so the AI can operate freely. Set MCP_KVM_ALLOW_DESTRUCTIVE=false (default) to prevent the most dangerous shortcuts.
• You control the AI. Treat MCP tools like any remote-execution capability and review what your AI is about to do before confirming.

Project relationship

mcp-kvm is the open-source core of the KiSum Bot project — a commercial AI worker platform for sysadmins and automation teams. The MCP server is Apache 2.0; premium enterprise features (Lexoffice / DATEV skills, team collaboration, audit logs) live in the private kisum platform.

If you like mcp-kvm, please star it and share your use case on GitHub Discussions.

Roadmap

• [x] v0.1 — Software, BliKVM, PiKVM adapters, 13 tools, npm + PyPI packaging
• [ ] v0.2 — Multi-display support, image-based click verification
• [ ] v0.3 — MCP Resources for knowledge injection (browser patterns, keyboard shortcuts)
• [ ] v0.4 — Context memory + action verification (AI remembers past actions, verifies success)
• [ ] v0.5 — run_task tool (built-in agent loop with self-healing and precision clicking)
• [ ] v1.0 — Stable API, entry-point adapter plugins, certified adapter list

Contributing

We actively welcome new KVM adapters, bug reports, and documentation improvements. See CONTRIBUTING.md (coming soon).

License

Apache 2.0 — see LICENSE.

Copyright 2026 ki-sum