# libvirt-mcp

A Model Context Protocol (MCP) server for managing KVM/QEMU virtual machines on remote
libvirt hosts. Talks libvirt RPC over SSH — no agent on the hypervisor, no need to
install anything on the target host beyond the standard `libvirtd`.

Functionally a "virt-manager for LLMs": inspect, start/stop, snapshot, clone, and delete
KVM/QEMU domains through 13 MCP tools.

## Tools

| Group | Tools |
| --- | --- |
| Inspection | `list_domains`, `domain_info`, `snapshot_list`, `screenshot` |
| Lifecycle | `start_domain`, `shutdown_domain` (ACPI + poll), `reboot_domain`, `force_destroy_domain` |
| Snapshots | `snapshot_create`, `snapshot_revert`, `snapshot_delete` |
| Management | `clone_from_template` (linked clone), `delete_domain` (with optional `wipe_disks`) |

Destructive operations (`force_destroy_domain`, `snapshot_revert`, `snapshot_delete`,
`delete_domain`) require an explicit `confirm=True` argument so an LLM can't fire them
by accident.

## Architecture

```
┌──────────────┐                          ┌──────────────────────┐
│ MCP client   │  ── stdio (JSON-RPC) ──▶ │ libvirt-mcp          │
│ Claude Code, │                          │ (Docker container)   │
│ Desktop, …   │                          │  • libvirt-python    │
└──────────────┘                          │  • mcp SDK           │
                                          └──────────┬───────────┘
                                                     │
                                                     │ qemu+ssh://user@host/system
                                                     │ (uses host's ~/.ssh/)
                                                     ▼
                                          ┌──────────────────────┐
                                          │ Hypervisor           │
                                          │  • libvirtd          │
                                          │  • qemu-kvm          │
                                          └──────────────────────┘
```

The MCP server runs inside a Docker container (so `libvirt-dev` headers don't need to
be installed on your machine). It bind-mounts your `~/.ssh` read-only and uses standard
libvirt SSH transport, inheriting `~/.ssh/config`, agent forwarding, jump hosts, etc.

## Setup

### 1. Pull the image

The container image is published as `ghcr.io/rzippert/libvirt-mcp` (public — no auth
required, even though the source repo is private):

```bash
docker pull ghcr.io/rzippert/libvirt-mcp:latest
```

Tags published:

- `latest` — head of `main`
- `X.Y.Z` and `X.Y` — from git tags `vX.Y.Z` (the `v` prefix is dropped per Docker convention)
- `main`, `sha-<short>` — for traceability

### 2. Create your config

```bash
mkdir -p ~/.config/libvirt-mcp
cat > ~/.config/libvirt-mcp/config.toml <<'EOF'
default_profile = "primary"

[profiles.primary]
uri = "qemu+ssh://user@hypervisor.example.com/system"
description = "Primary KVM hypervisor"
EOF
$EDITOR ~/.config/libvirt-mcp/config.toml
```

The libvirt URI is standard. SSH keys come from your host's `~/.ssh/`. Make sure you
can already connect:

```bash
ssh user@hypervisor.example.com virsh -c qemu:///system list --all
```

### 3. Wire it up to an MCP client

#### Claude Code

```bash
claude mcp add libvirt --scope user -- \
  docker run -i --rm \
    -v "$HOME/.ssh:/home/ubuntu/.ssh:ro" \
    -v "$HOME/.config/libvirt-mcp/config.toml:/etc/libvirt-mcp/config.toml:ro" \
    --network host \
    -e LIBVIRT_MCP_CONFIG=/etc/libvirt-mcp/config.toml \
    ghcr.io/rzippert/libvirt-mcp:latest
```

Verify with `claude mcp list`. Remove with `claude mcp remove libvirt --scope user`.

#### Claude Desktop

Edit `claude_desktop_config.json`:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "libvirt": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/youruser/.ssh:/home/ubuntu/.ssh:ro",
        "-v", "/Users/youruser/.config/libvirt-mcp/config.toml:/etc/libvirt-mcp/config.toml:ro",
        "--network", "host",
        "-e", "LIBVIRT_MCP_CONFIG=/etc/libvirt-mcp/config.toml",
        "ghcr.io/rzippert/libvirt-mcp:latest"
      ]
    }
  }
}
```

Replace `/Users/youruser` with your home directory. On Windows use forward slashes or
double-escape backslashes. Restart Claude Desktop after editing.

#### VS Code (GitHub Copilot Chat MCP)

Create `.vscode/mcp.json` in your workspace (project-scoped) or add to user settings:

```json
{
  "servers": {
    "libvirt": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "${userHome}/.ssh:/home/ubuntu/.ssh:ro",
        "-v", "${userHome}/.config/libvirt-mcp/config.toml:/etc/libvirt-mcp/config.toml:ro",
        "--network", "host",
        "-e", "LIBVIRT_MCP_CONFIG=/etc/libvirt-mcp/config.toml",
        "ghcr.io/rzippert/libvirt-mcp:latest"
      ]
    }
  }
}
```

VS Code expands `${userHome}` and `${workspaceFolder}`. Open the Copilot Chat panel →
MCP servers → enable `libvirt`.

## Configuration reference

`~/.config/libvirt-mcp/config.toml` (or override with `LIBVIRT_MCP_CONFIG`):

```toml
default_profile = "primary"   # used when a tool is called without `profile=`

[profiles.<name>]
uri = "qemu+ssh://user@host/system"   # standard libvirt URI
description = "Free-form description for humans"
```

Config search order:

1. `$LIBVIRT_MCP_CONFIG` env var
2. `~/.config/libvirt-mcp/config.toml`
3. `./config.dev.toml`
4. `./config.toml`

## Safety model

- **Allow-list validation** on domain names (`^[a-z0-9][a-z0-9-]{0,30}$`), bridge names,
  and absolute paths (no `..` segments).
- **Inspection tools** open read-only libvirt connections; **state-changing tools** open
  read-write connections only when invoked.
- **Confirmation gates** on destructive operations: `force_destroy_domain`,
  `snapshot_revert`, `snapshot_delete`, `delete_domain` all require `confirm=True`.
- **No subprocess** on the hypervisor: every operation is pure libvirt RPC (no
  `qemu-img`, no `virt-install`, no `virsh` shell-out). Disk volumes are created and
  deleted through libvirt's storage volume API, reusing any active dir-pool that
  covers the target path or transparently creating a transient one.

## Development

```bash
git clone git@github.com:rzippert/libvirt-mcp.git
cd libvirt-mcp
cp config.example.toml config.dev.toml && $EDITOR config.dev.toml
docker compose build
docker compose run --rm dev bash
```

Inside the dev container, source on the host (bind-mounted at `/workspace`) shadows the
installed package via `PYTHONPATH`, so edits take effect immediately. Exercise tools
directly:

```bash
python -c "from libvirt_mcp.tools.readonly import list_domains; \
           import json; print(json.dumps(list_domains(), indent=2))"
```

Project layout:

```
libvirt_mcp/
├── __main__.py        # python -m libvirt_mcp → mcp.run() (stdio)
├── server.py          # FastMCP instance
├── connections.py     # config loader + connect() context manager
├── states.py          # VIR_DOMAIN_* → string
└── tools/
    ├── readonly.py    # inspection
    ├── lifecycle.py   # start/shutdown/reboot/force_destroy
    ├── snapshot.py    # snapshot CRUD (revert/delete gated)
    └── management.py  # clone_from_template, delete_domain
```

Publishing happens automatically via `.github/workflows/publish.yml` on push to `main`
and on `v*` tags (multi-arch: `linux/amd64`, `linux/arm64`).

## License

GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See [LICENSE](LICENSE).