KVM MCP Server

KVM MCP Server

功能强大的 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 进行本地安装
  • 支持多种 OS 变体
  • 自动配置安装

• 性能优化：

  • 为 libvirt 使用连接池，降低连接开销
  • 缓存 VM 信息，提升响应速度
  • 异步处理，提升并发能力
  • 提供高级日志记录，便于诊断和排查问题
  • 妥善处理优雅关闭，正确清理资源
  • 自动恢复和验证连接
  • 限制 API 操作的速率
  • 收集性能指标

性能优势

连接池

• 降低延迟：避免反复打开和关闭 libvirt 连接带来的开销
• 提高资源效率：维护可复用的连接池，减少系统资源使用
• 自动恢复：自动检测并替换失效连接
• 可配置池大小：根据工作负载调整连接数

缓存

• 缩短响应时间：减少常见操作对 libvirt 的重复查询
• 可配置 TTL：根据需要设置缓存过期时间
• 选择性绕过：对于需要最新数据的操作，可选择绕过缓存
• 自动失效：VM 状态发生变化时自动使缓存失效

异步处理

• 提升并发能力：同时处理多个请求
• 更好地利用资源：高效使用系统资源
• 非阻塞操作：长时间运行的操作不会阻塞服务
• 优雅关闭：关闭期间妥善清理资源

监控和诊断

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

配置

服务器使用 JSON 配置文件（config.json）存储默认值和路径。这让服务器更易于移植和自定义。配置包括：

{
    "vm": {
        "disk_path": "/vm",                    // Base directory for VM disk storage
        "default_iso": "/iso/ubuntu-24.04.2-live-server-amd64.iso",  // Default installation media for Ubuntu-based VMs
        "default_master_image": "/iso/fedora-coreos-41-qemu.x86_64.qcow2",  // Default base image for Fedora CoreOS VMs
        "default_name": "newvmname",           // Default VM name
        "default_memory": 2048,                // Default memory allocation in MB
        "default_vcpus": 2,                    // Default number of virtual CPUs
        "default_disk_size": 20,               // Default disk size in GB
        "default_os_variant": "generic",       // Default OS variant for virt-install
        "default_network": "brforvms",         // Default network bridge for VM networking
        "ignition": {                          // Fedora CoreOS specific configuration
            "default_hostname": "coreos",      // Default hostname for CoreOS VMs
            "default_user": "core",            // Default user for CoreOS VMs
            "default_ssh_key": "~/.ssh/id_rsa.pub",  // Default SSH public key path
            "default_timezone": "UTC",         // Default timezone
            "default_locale": "en_US.UTF-8",   // Default system locale
            "default_password_hash": null      // Optional: Default password hash for user
        }
    }
}

你可以修改这些值以满足环境需求。配置支持通过以下格式使用环境变量覆盖：

• 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

性能调优

连接池配置

connection_pool = LibvirtConnectionPool(
    max_connections=5,     # Maximum number of connections in the pool
    timeout=30,            # Timeout for getting a connection (seconds)
    uri='qemu:///system'   # Libvirt connection URI
)

缓存配置

vm_info_cache = VMInfoCache(
    max_size=50,           # Maximum number of VMs to cache
    ttl=60                 # Time-to-live for cache entries (seconds)
)

日志配置

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. 克隆此仓库：

   git clone https://github.com/yourusername/kvm-mcp.git
   cd kvm-mcp
   

2. 创建并激活虚拟环境：

   python3 -m venv .venv
   source .venv/bin/activate
   

3. 安装依赖项：

   pip install -r requirements.txt
   

4. 配置服务器：

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

使用方法

1. 启动服务器：

   python3 kvm_mcp_server.py
   

2. 使用 JSON-RPC 发送命令。示例脚本如下：

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

命令示例

创建新的 VM

./create_vm.sh

这将使用 config.json 中的默认配置创建新的 VM。你可以在请求中提供相应值，以覆盖任意默认值。

查找 VNC 端口

./get_vnc_ports.sh

这将显示所有运行中 VM 及其 VNC 端口，方便连接到它们的显示器。

绕过缓存列出 VM

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_connections

2. 缓存失效问题

   • 症状：VM 信息过时
   • 解决方案：使用 no_cache 参数或缩短缓存 TTL

3. 资源清理

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

项目结构

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

贡献

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

许可证

本项目采用 MIT License 授权，详情请参阅 LICENSE 文件。