KVM MCP 服务器

一个强大的 JSON-RPC 服务器，通过简单直观的界面管理 KVM 虚拟机。该服务器提供了一种集中化的方式来使用标准化协议控制和监控您的 KVM 虚拟机。

为什么选择这个项目？

管理 KVM 虚拟机通常需要使用多个命令行工具，如 virsh、virt-install 和 qemu-system。本项目旨在：

1. 简化 VM 管理：为所有 VM 操作提供单一、统一的接口
2. 启用远程控制：通过 JSON-RPC 允许远程管理 VM
3. 自动化 VM 操作：使脚本编写和自动化 VM 管理任务变得容易
4. 标准化 VM 配置：确保在整个基础设施中一致的 VM 设置
5. 优化性能：实现高效的资源管理和缓存策略

功能

• VM 生命周期管理：

  • 使用可自定义参数创建新的 VM
  • 启动/停止/重启 VM
  • 列出所有可用的 VM 及其状态
  • 自动状态跟踪和恢复

• 网络管理：

  • 使用桥接配置 VM 网络
  • 支持 brforvms 桥
  • 自动网络接口配置
  • IP 地址跟踪和管理

• 存储管理：

  • 可配置的 VM 磁盘存储位置
  • 支持多种磁盘格式（qcow2）
  • 可配置的磁盘大小
  • 自动磁盘清理和管理

• 显示管理：

  • 支持 VNC 图形访问
  • 自动 VNC 端口分配
  • 查找和连接到 VM 显示的工具
  • 显示状态跟踪和恢复

• 安装支持：

  • 从 ISO 镜像进行网络安装
  • 从 CDROM 进行本地安装
  • 支持多种操作系统变体
  • 自动化安装配置

• 性能优化：

  • libvirt 的连接池以减少连接开销
  • VM 信息缓存以提高响应速度
  • 异步处理以提高并发性
  • 高级日志记录用于诊断和故障排除
  • 正确的关机处理以进行适当的资源清理
  • 自动连接恢复和验证
  • API 操作的速率限制
  • 性能指标收集

性能优势

连接池

• 降低延迟：消除反复打开和关闭 libvirt 连接的开销
• 资源效率：维护一组可重用的连接，减少系统资源使用
• 自动恢复：自动检测并替换死连接
• 可配置的池大小：根据工作负载调整连接数量

缓存

• 更快的响应时间：减少对常见操作的重复查询
• 可配置的 TTL：根据需要设置缓存过期时间
• 选择性绕过：对于需要最新数据的操作可以选择绕过缓存
• 自动失效：当 VM 状态更改时自动使缓存失效

异步处理

• 改进的并发性：同时处理多个请求
• 更好的资源利用率：高效利用系统资源
• 非阻塞操作：长时间运行的操作不会阻塞服务器
• 优雅关机：在关机期间正确清理资源

监控和诊断

• 结构化日志：易于解析的日志格式，便于分析
• 性能指标：跟踪操作时间和资源使用情况
• 错误跟踪：详细的错误日志，便于故障排除
• 资源监控：跟踪连接池使用情况和缓存效果

配置

服务器使用 JSON 配置文件 (config.json) 存储默认值和路径。这使得服务器更便携且更容易定制。配置包括：

json
{
"vm": {
"disk_path": "/vm", // VM 磁盘存储的基本目录
"default_iso": "/iso/ubuntu-24.04.2-live-server-amd64.iso", // 基于 Ubuntu 的 VM 的默认安装介质
"default_master_image": "/iso/fedora-coreos-41-qemu.x86_64.qcow2", // Fedora CoreOS VM 的默认基础镜像
"default_name": "newvmname", // 默认 VM 名称
"default_memory": 2048, // 默认内存分配（MB）
"default_vcpus": 2, // 默认虚拟 CPU 数量
"default_disk_size": 20, // 默认磁盘大小（GB）
"default_os_variant": "generic", // virt-install 的默认操作系统变体
"default_network": "brforvms", // VM 网络的默认网络桥
"ignition": { // Fedora CoreOS 特定配置
"default_hostname": "coreos", // CoreOS VM 的默认主机名
"default_user": "core", // CoreOS VM 的默认用户
"default_ssh_key": "~/.ssh/id_rsa.pub", // 默认 SSH 公钥路径
"default_timezone": "UTC", // 默认时区
"default_locale": "en_US.UTF-8", // 默认系统区域设置
"default_password_hash": null // 可选：用户的默认密码哈希
}
}
}您可以根据环境需求修改这些值。配置支持使用以下格式的环境变量覆盖：

• VM_DISK_PATH 用于 disk_path
• VM_DEFAULT_ISO 用于 default_iso
• VM_DEFAULT_MASTER_IMAGE 用于 default_master_image
• VM_DEFAULT_NAME 用于 default_name
• VM_DEFAULT_MEMORY 用于 default_memory
• VM_DEFAULT_VCPUS 用于 default_vcpus
• VM_DEFAULT_DISK_SIZE 用于 default_disk_size
• VM_DEFAULT_OS_VARIANT 用于 default_os_variant
• VM_DEFAULT_NETWORK 用于 default_network
• VM_IGNITION_DEFAULT_HOSTNAME 用于 ignition.default_hostname
• VM_IGNITION_DEFAULT_USER 用于 ignition.default_user
• VM_IGNITION_DEFAULT_SSH_KEY 用于 ignition.default_ssh_key
• VM_IGNITION_DEFAULT_TIMEZONE 用于 ignition.default_timezone
• VM_IGNITION_DEFAULT_LOCALE 用于 ignition.default_locale
• VM_IGNITION_DEFAULT_PASSWORD_HASH 用于 ignition.default_password_hash

性能调优

连接池配置

python
connection_pool = LibvirtConnectionPool(
max_connections=5, # 连接池中的最大连接数
timeout=30, # 获取连接的超时时间（秒）
uri='qemu:///system' # Libvirt 连接 URI
)

缓存配置

python
vm_info_cache = VMInfoCache(
max_size=50, # 缓存的最大虚拟机数量
ttl=60 # 缓存条目的生存时间（秒）
)

日志配置

python
logging.basicConfig(
level=logging.INFO,
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
handlers=[
RotatingFileHandler(
'kvm_mcp.log',
maxBytes=10485760, # 10MB
backupCount=5
),
logging.StreamHandler()
]
)

入门指南

前提条件

• Python 3.6 或更高版本
• 主机系统上安装了 KVM 和 libvirt
• 配置网络桥接（默认：brforvms）
• 创建 VM 存储目录（默认：/vm/）
• 系统资源足以支持您的 VM 工作负载

安装

1. 克隆此仓库：
   bash
   git clone https://github.com/yourusername/kvm-mcp.git
   cd kvm-mcp

2. 创建并激活虚拟环境：
   bash
   python3 -m venv .venv
   source .venv/bin/activate

3. 安装依赖项：
   bash
   pip install -r requirements.txt

4. 配置服务器：

   • 编辑 config.json 以匹配您的环境
   • 确保所有必需的目录存在
   • 验证网络桥接配置
   • 根据需要调整性能设置

使用方法

1. 启动服务器：
   bash
   python3 kvm_mcp_server.py

2. 使用 JSON-RPC 发送命令。示例脚本已提供：

   • create_vm.sh: 使用默认配置创建一个新的 VM
   • get_vnc_ports.sh: 查找运行中的 VM 的 VNC 端口

示例命令

创建新的 VM

bash
./create_vm.sh

这将使用 config.json 中的默认配置创建一个新的 VM。您可以通过在请求中提供它们来覆盖任何这些默认值。

查找 VNC 端口

bash
./get_vnc_ports.sh

这将显示所有运行中的 VM 及其 VNC 端口，使连接到它们的显示变得容易。

列出 VM 并绕过缓存

bash
echo '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "list_vms", "arguments": {"no_cache": true}}, "id": 1}' | python3 kvm_mcp_server.py

监控和故障排除

日志文件

• kvm_mcp.log: 当前日志文件
• kvm_mcp.log.1: 上一个日志文件（已轮转）
• 日志包括时间信息、连接池状态和缓存命中/未命中情况

性能指标

• 连接池使用统计
• 缓存命中/未命中比率
• 操作时间度量
• 资源利用率统计

常见问题及解决方案

1. 连接池耗尽

   • 症状：响应时间慢或连接错误
   • 解决方案：在连接池配置中增加 max_connections2. 缓存失效问题
   • 症状：陈旧的虚拟机信息
   • 解决方案：使用 no_cache 参数或减少缓存 TTL

2. 资源清理

   • 症状：资源泄漏或连接问题
   • 解决方案：确保使用 SIGTERM 或 SIGINT 正确关闭

项目结构

• kvm_mcp_server.py：主服务器实现
• config.json：配置文件
• requirements.txt：Python 依赖项
• 根目录中的示例脚本
• tests/ 目录中的测试套件

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。