内容
# libvirt-mcp
一个用于管理远程libvirt主机上的KVM/QEMU虚拟机的模型上下文协议（MCP）服务器。通过SSH进行libvirt RPC通信——无需在超级管理程序上安装代理或任何其他软件，只需安装标准的`libvirtd`。
功能上类似于“LLM的虚拟机管理器（virt-manager）”：通过13个MCP工具检查、启动/停止、快照、克隆和删除KVM/QEMU域。
## 工具
| 组 | 工具 |
| --- | --- |
| 检查 | `list_domains`, `domain_info`, `snapshot_list`, `screenshot` |
| 生命周期 | `start_domain`, `shutdown_domain`（ACPI + 轮询）, `reboot_domain`, `force_destroy_domain` |
| 快照 | `snapshot_create`, `snapshot_revert`, `snapshot_delete` |
| 管理 | `clone_from_template`（链接克隆）, `delete_domain`（可选`wipe_disks`） |
破坏性操作（`force_destroy_domain`, `snapshot_revert`, `snapshot_delete`, `delete_domain`）需要显式`confirm=True`参数，以防止LLM意外触发。
## 架构
```
┌──────────────┐ ┌──────────────────────┐
│ MCP 客户端 │ ── 标准输入/输出（JSON-RPC） ──▶ │ libvirt-mcp │
│ Claude 代码, │ │ （Docker 容器） │
│ 桌面, … │ │ • libvirt-python │
└──────────────┘ │ • mcp SDK │
└──────────┬───────────┘
│
│ qemu+ssh://用户@主机/system
│ （使用主机的 ~/.ssh/）
▼
┌──────────────────────┐
│ 超级管理程序 │
│ • libvirtd │
│ • qemu-kvm │
└──────────────────────┘
```
MCP服务器在Docker容器中运行（因此您的机器上不需要安装`libvirt-dev`头文件）。它绑定安装您的`~/.ssh`目录为只读，并使用标准的libvirt SSH传输，继承`~/.ssh/config`、代理转发、跳转主机等。
## 设置
### 1. 拉取镜像
容器镜像发布为`ghcr.io/rzippert/libvirt-mcp`（公开 - 无需身份验证，尽管源代码仓库是私有的）：
```bash
docker pull ghcr.io/rzippert/libvirt-mcp:latest
```
发布的标签：
- `latest` — `main`分支的最新版本
- `X.Y.Z` 和 `X.Y` — 来自git标签`vX.Y.Z`（`v`前缀按照Docker惯例被删除）
- `main`, `sha-<short>` — 为了可追溯性
### 2. 创建配置文件
```bash
mkdir -p ~/.config/libvirt-mcp
cat > ~/.config/libvirt-mcp/config.toml <<'EOF'
default_profile = "primary"
[profiles.primary]
uri = "qemu+ssh://用户@超级管理程序.example.com/system"
description = "主要KVM超级管理程序"
EOF
$EDITOR ~/.config/libvirt-mcp/config.toml
```
libvirt URI是标准的。SSH密钥来自主机的`~/.ssh/`目录。确保您可以已经连接：
```bash
ssh 用户@超级管理程序.example.com virsh -c qemu:///system list --all
```
### 3. 连接到MCP客户端
#### Claude 代码
```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
```
使用`claude mcp list`验证。使用`claude mcp remove libvirt --scope user`删除。
#### Claude 桌面
编辑`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"
]
}
}
}
```
替换`/Users/youruser`为主目录路径。在Windows上使用正斜杠或双反斜杠。编辑后重启Claude Desktop。
#### VS Code（GitHub Copilot Chat MCP）
在工作区（项目范围）中创建`.vscode/mcp.json`或添加到用户设置：
```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扩展`${userHome}`和`${workspaceFolder}`。打开Copilot聊天面板→MCP服务器→启用`libvirt`。
## 配置参考
`~/.config/libvirt-mcp/config.toml`（或使用`LIBVIRT_MCP_CONFIG`覆盖）：
```toml
default_profile = "primary" # 在调用工具时没有`profile=`参数时使用
[profiles.<name>]
uri = "qemu+ssh://用户@主机/system" # 标准libvirt URI
description = "人类自由格式描述"
```
配置搜索顺序：
1. `$LIBVIRT_MCP_CONFIG` 环境变量
2. `~/.config/libvirt-mcp/config.toml`
3. `./config.dev.toml`
4. `./config.toml`
## 安全模型
- **允许列表验证**：域名（`^[a-z0-9][a-z0-9-]{0,30}$`）、桥接名称和绝对路径（无`..`段）。
- **检查工具**打开只读libvirt连接；**状态更改工具**仅在调用时打开读写连接。
- **确认门控**：破坏性操作：`force_destroy_domain`, `snapshot_revert`, `snapshot_delete`, `delete_domain`都需要`confirm=True`。
- **超级管理程序上无子进程**：每个操作都是纯libvirt RPC（无`qemu-img`，无`virt-install`，无`virsh` shell-out）。磁盘卷通过libvirt的存储卷API创建和删除，重用任何涵盖目标路径的活动目录池或透明地创建临时目录池。
## 开发
```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
```
在开发容器中，主机上的源代码（绑定安装在`/workspace`）通过`PYTHONPATH`覆盖已安装的包，因此编辑立即生效。直接执行工具：
```bash
python -c "from libvirt_mcp.tools.readonly import list_domains; \
import json; print(json.dumps(list_domains(), indent=2))"
```
项目布局：
```
libvirt_mcp/
├── __main__.py # python -m libvirt_mcp → mcp.run() （标准输入/输出）
├── server.py # FastMCP 实例
├── connections.py # 配置加载器 + connect() 上下文管理器
├── states.py # VIR_DOMAIN_* → 字符串
└── tools/
├── readonly.py # 检查
├── lifecycle.py # 启动/关闭/重启/强制销毁
├── snapshot.py # 快照CRUD（恢复/删除门控）
└── management.py # clone_from_template, delete_domain
```
发布通过 `.github/workflows/publish.yml` 在 `main` 分支和 `v*` 标签上自动进行（多架构：`linux/amd64`，`linux/arm64`）。
## 许可证
GNU Affero通用公共许可证第3版或更高版本（AGPL-3.0-or-later）。请参阅 [LICENSE](LICENSE)。
