# kvm-pilot

MCP server for managing bare-metal machines over IP-KVM, BMC, and SSH without installing background software on the target.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 9
- Author: DustinTrap
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/DustinTrap/kvm-pilot
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/mcp/kvm-pilot

## What it does

The server connects language models directly to physical hardware using IP-KVM adapters, BMC controllers like Redfish and IPMI, or Intel AMT. Target machines require zero host software. Control happens entirely via external display capture and virtual input devices, allowing agents to navigate POST screens, BIOS menus, bootloaders, and OS setups.

Visual analysis runs through Claude or any local vision model running on Ollama, LM Studio, or vLLM. Using an on-premises model keeps all captured frames strictly inside the local network. Safety measures prevent unintended modifications: setting `KVM_PILOT_MCP_READ_ONLY=1` restricts the agent to observation until explicitly relaxed.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `KVM_PILOT_PROFILE`, `KVM_PILOT_MCP_READ_ONLY`, `KVM_PILOT_MCP_DRY_RUN`, `KVM_PILOT_MCP_ALLOW_POWER`, `KVM_PILOT_HOST`, `KVM_PILOT_USER`, `KVM_PILOT_PASSWD`, `ANTHROPIC_API_KEY` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env KVM_PILOT_PROFILE=<KVM_PILOT_PROFILE> --env KVM_PILOT_MCP_READ_ONLY=<KVM_PILOT_MCP_READ_ONLY> --env KVM_PILOT_MCP_DRY_RUN=<KVM_PILOT_MCP_DRY_RUN> --env KVM_PILOT_MCP_ALLOW_POWER=<KVM_PILOT_MCP_ALLOW_POWER> --env KVM_PILOT_HOST=<KVM_PILOT_HOST> --transport stdio kvm-pilot -- uvx kvm-pilot
```
Replace <…> with your own values. 3 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from kvm-pilot <command>

### Codex

**Platform CLI**
```bash
codex mcp add kvm-pilot --env KVM_PILOT_PROFILE=<KVM_PILOT_PROFILE> --env KVM_PILOT_MCP_READ_ONLY=<KVM_PILOT_MCP_READ_ONLY> --env KVM_PILOT_MCP_DRY_RUN=<KVM_PILOT_MCP_DRY_RUN> --env KVM_PILOT_MCP_ALLOW_POWER=<KVM_PILOT_MCP_ALLOW_POWER> --env KVM_PILOT_HOST=<KVM_PILOT_HOST> -- uvx kvm-pilot
```
Replace <…> with your own values. 3 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from kvm-pilot <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "kvm-pilot": {
            "command": "uvx",
            "args": [
                "kvm-pilot"
            ],
            "env": {
                "KVM_PILOT_PROFILE": "<KVM_PILOT_PROFILE>",
                "KVM_PILOT_MCP_READ_ONLY": "<KVM_PILOT_MCP_READ_ONLY>",
                "KVM_PILOT_MCP_DRY_RUN": "<KVM_PILOT_MCP_DRY_RUN>",
                "KVM_PILOT_MCP_ALLOW_POWER": "<KVM_PILOT_MCP_ALLOW_POWER>",
                "KVM_PILOT_HOST": "<KVM_PILOT_HOST>"
            }
        }
    }
}
```
Replace <…> with your own values. 3 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from kvm-pilot <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "kvm-pilot": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "kvm-pilot"
            ],
            "env": {
                "KVM_PILOT_PROFILE": "<KVM_PILOT_PROFILE>",
                "KVM_PILOT_MCP_READ_ONLY": "<KVM_PILOT_MCP_READ_ONLY>",
                "KVM_PILOT_MCP_DRY_RUN": "<KVM_PILOT_MCP_DRY_RUN>",
                "KVM_PILOT_MCP_ALLOW_POWER": "<KVM_PILOT_MCP_ALLOW_POWER>",
                "KVM_PILOT_HOST": "<KVM_PILOT_HOST>"
            }
        }
    }
}
```
Replace <…> with your own values. 3 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from kvm-pilot <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e KVM_PILOT_PROFILE=<KVM_PILOT_PROFILE> -e KVM_PILOT_MCP_READ_ONLY=<KVM_PILOT_MCP_READ_ONLY> -e KVM_PILOT_MCP_DRY_RUN=<KVM_PILOT_MCP_DRY_RUN> -e KVM_PILOT_MCP_ALLOW_POWER=<KVM_PILOT_MCP_ALLOW_POWER> -e KVM_PILOT_HOST=<KVM_PILOT_HOST> kvm-pilot uvx kvm-pilot
```
Replace <…> with your own values. 3 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from kvm-pilot <command>

## When to use it
- interact with BIOS menus and bootloaders on headless servers
- automate OS setup routines without network access inside the guest
- monitor hardware boot progress using vision backends
- trigger remote power cycles through BMC or KVM interfaces

## Example prompts
- Take a frame capture of the current display and check which boot stage the machine is in.
- Wait until the screen reaches the GRUB prompt and press Enter.
- Check remote hardware power status in read-only mode.

## Similar
- [qemu-kvm](https://affpapa.org/en/nevibecode/skills/qemu-kvm.md) — skill · 304 installs
- [dolphin-mcp-pilot](https://affpapa.org/en/nevibecode/mcp/dolphin-mcp-pilot.md) — MCP server · ★ 21
- [zeroboot-vm-sandbox](https://affpapa.org/en/nevibecode/skills/zeroboot-vm-sandbox.md) — skill · 1300 installs
- [proxmox-admin](https://affpapa.org/en/nevibecode/skills/proxmox-admin.md) — skill · 828 installs
- [pcbway](https://affpapa.org/en/nevibecode/skills/pcbway.md) — skill · 483 installs
- [jetson-llm-serve](https://affpapa.org/en/nevibecode/skills/jetson-llm-serve.md) — skill · 1200 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md