AI导哈

虚拟机管理服务器

一个通过SSH远程管理libvirt主机上虚拟机的MCP服务器，适用于本地开发和测试环境。

  • by chrisjohntapp
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 chrisjohntapp/libvirt-mcp

使用说明

libvirt mcp

一个MCP服务器，用于通过SSH管理远程libvirt主机上的虚拟机。 设计用于在笔记本电脑上本地运行并连接到一个或多个管理程序。

需求

  • Python 3.10+
  • libvirt 本地安装的C库（用于 libvirt-python)
  • 使用基于密钥的身份验证通过SSH访问libvirt主机
  • libvirtd 在每个远程主机上运行

安装libvirt系统库

macOS（Homebrew）：

brew install libvirt

Ubuntu/Debian：

sudo apt install libvirt-dev python3-dev

Fedora/RHEL：

sudo dnf install libvirt-devel python3-devel

安装

cd libvirt-mcp
pip install -e .

或使用紫外线（推荐）：

uv pip install -e .

用法

手动运行服务器（用于测试）

python server.py

服务器使用 stdio传输 --它被设计为由MCP发射 客户端（Claude Code、Claude Desktop等），不作为长期守护进程运行。

测试

单元测试在没有真正的libvirt主机的情况下运行。集成测试需要 LIBVIRT_TEST_HOST.

如果 LIBVIRT_TEST_HOST 存储在 .env，将其导出到当前shell中 在运行pytest之前：

set -a; source .env; set +a

运行测试：

# Unit tests
uv run pytest tests/test_server.py -v

# Integration tests
uv run pytest tests/test_integration.py -v

# Full suite
uv run pytest tests/ -v

使用 -rs 诊断跳过时：

uv run pytest tests/test_integration.py -v -rs

MCP检验员测试

npx @modelcontextprotocol/inspector python server.py

使用Claude代码进行配置

添加到您的Claude Code MCP配置中(~/.claude/claude_mcp_config.json):

{
  "mcpServers": {
    "libvirt": {
      "command": "python",
      "args": ["/path/to/libvirt-mcp/server.py"]
    }
  }
}

或使用 uv run 如果您是通过uv安装的：

{
  "mcpServers": {
    "libvirt": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/libvirt-mcp", "python", "server.py"]
    }
  }
}

可用工具

连接管理

工具 说明
libvirt_connect_host 打开与libvirt主机的SSH连接，在别名下注册
libvirt_disconnect_host 关闭与主机的连接
libvirt_list_hosts 显示所有活动主机连接

VM创建

工具 说明
libvirt_create_vm 从模板创建虚拟机（配置磁盘、定义、启动）
libvirt_list_templates 列出可用的VM模板

VM迁移

工具 说明
libvirt_migrate_vm 将脱机迁移作为异步作业启动（关闭、复制磁盘、定义/启动目标）
libvirt_get_migration_status 获取迁移作业状态、阶段时间线和最终结果/错误

迁移流程：

  1. 呼叫 libvirt_migrate_vm 随着 confirm=false 和捕获 job_id
  2. 投票与 libvirt_get_migration_status 直到状态为 succeeded 或 failed
  3. 呼叫 libvirt_migrate_vm 随着 confirm=true 清理源定义/磁盘

域生命周期

工具 描述 破坏性？
libvirt_list_domains 列出所有虚拟机，可选择按状态筛选 否
libvirt_get_domain_info 获取特定VM的详细信息 否
libvirt_get_domain_xml 检索VM的完整XML定义 否
libvirt_define_domain 从XML注册新VM 否
libvirt_start_domain 启动关闭VM 否
libvirt_shutdown_domain 发送优雅的ACPI关机信号 否
libvirt_destroy_domain 强制停止VM（电源拉动） 是
libvirt_reboot_domain 发送优雅的重启信号 否
libvirt_suspend_domain 暂停/冻结正在运行的虚拟机 否
libvirt_resume_domain 取消暂停VM的暂停 否
libvirt_undefine_domain 从libvirt中删除VM定义 是

本地环境配置

创建一个 .lab/hosts.json 用于定义libvirt主机的文件（此目录为 git忽略）：

mkdir -p .lab

{
  "hosts": [
    {
      "host": "myhost.example.com",
      "alias": "myhost"
    }
  ]
}

每个条目支持与以下相同的字段 libvirt_connect_host: host （必填）， alias （必填）， user （可选）， port （可选）， ssh_key_path （可选）。

模板

VM模板是JSON文件 templates/ 目录。其中包括两个：

  • default --带有新的10GB空磁盘的基本KVM VM
  • suse-leap-micro --复制openSUSE Leap Micro基础映像

通过添加JSON文件来创建自己的文件 templates/。有关架构，请参阅现有模板。

创建虚拟机

“使用带有2个vCPU和2048 MB RAM的默认模板在实验室中创建一个名为'web01'的VM”

这将通过SSH在远程主机上提供磁盘，生成域XML，定义并启动VM。

与克劳德的对话示例

连接到我的实验室主机： 以用户ubuntu的身份连接到我的libvirt主机192.168.1.10，别名为“lab”

列出虚拟机： “列出实验室中所有正在运行的虚拟机”

启动虚拟机： 在实验室中启动名为“ubuntu服务器”的虚拟机

获取XML进行编辑： “在实验室中获取'ubuntu服务器'的XML，这样我就可以调整它的内存”

扩展服务器

要添加的未来模块（每个模块都在一个单独的文件中，导入到server.py中）：

  • storage.py --存储池、卷、磁盘连接/分离
  • networks.py --虚拟网络、接口
  • snapshots.py --快照创建/列表/还原/删除
  • clone.py --域克隆助手

安全须知

  • 使用SSH进行传输——不需要打开libvirt TCP端口
  • SSH密钥路径可以为每台主机指定，也可以依赖SSH代理
  • 破坏性行动(destroy, undefine)相应地进行了注释 因此MCP客户端可以在执行之前发出警告
  • 从不存储凭据--依赖于SSH密钥基础架构

相关 MCP