KVM MCP 服务器

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

为什么要开展这个项目？

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

简化虚拟机管理：为所有虚拟机操作提供单一、统一的界面
启用远程控制：允许通过 JSON-RPC 远程管理虚拟机
自动化虚拟机操作：轻松编写脚本并自动化虚拟机管理任务
标准化虚拟机配置：确保整个基础架构中的虚拟机设置一致
优化性能：实施高效的资源管理和缓存策略

特征

VM生命周期管理：
- 使用可自定义参数创建新的虚拟机
- 启动/停止/重启虚拟机
- 列出所有可用的虚拟机及其状态
- 自动状态跟踪和恢复
网络管理：
- 使用网桥配置虚拟机网络
- 支持brforvms桥
- 自动网络接口配置
- IP地址跟踪和管理
存储管理：
- 可配置虚拟机磁盘存储位置
- 支持多种磁盘格式（qcow2）
- 可配置的磁盘大小
- 自动磁盘清理和管理
显示管理：
- VNC 支持图形访问
- 自动 VNC 端口分配
- 查找并连接 VM 显示器的工具
- 显示状态跟踪和恢复
安装支持：
- 从 ISO 映像进行网络安装
- 从 CDROM 进行本地安装
- 支持各种操作系统
- 自动化安装配置
性能优化：
- libvirt 的连接池可减少连接开销
- VM 信息缓存以提高响应速度
- 异步处理以实现更好的并发性
- 用于诊断和故障排除的高级日志记录
- 优雅关机处理，以正确清理资源
- 自动连接恢复和验证
- API 操作的速率限制
- 性能指标收集

性能优势

连接池

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

缓存

更快的响应时间：减少对 libvirt 常见操作的重复查询
可配置 TTL ：根据您的需要设置缓存过期时间
选择性绕过：对于需要新数据的操作，可选择绕过缓存
自动失效：虚拟机状态改变时缓存自动失效

异步处理

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

监控和诊断

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

配置

该服务器使用 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/ ）
为您的虚拟机工作负载提供足够的系统资源

安装

克隆此存储库：
git clone https://github.com/yourusername/kvm-mcp.git cd kvm-mcp
创建并激活虚拟环境：
python3 -m venv .venv source .venv/bin/activate
安装依赖项：
pip install -r requirements.txt
配置服务器：
- 编辑config.json以匹配您的环境
- 确保所有必需的目录都存在
- 验证网桥配置
- 根据需要调整性能设置

用法

启动服务器：
python3 kvm_mcp_server.py
使用 JSON-RPC 发送命令。提供示例脚本：
- create_vm.sh ：使用默认配置创建新的虚拟机
- get_vnc_ports.sh ：查找正在运行的虚拟机的 VNC 端口

示例命令

创建新的虚拟机

./create_vm.sh

这将使用config.json中的默认配置创建一个新的虚拟机。你可以在请求中提供这些默认配置来覆盖它们。

查找 VNC 端口

./get_vnc_ports.sh

这将显示所有正在运行的虚拟机及其 VNC 端口，从而可以轻松连接到它们的显示器。

列出具有缓存绕过的虚拟机

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 ：上一个日志文件（已轮换）
日志包括时间信息、连接池状态和缓存命中/未命中

绩效指标

连接池使用情况统计
缓存命中/未命中率
操作时序指标
资源利用率统计

常见问题和解决方案

连接池耗尽
- 症状：响应时间缓慢或连接错误
- 解决方案：增加连接池配置中的max_connections
缓存失效问题
- 症状：虚拟机信息过时
- 解决方案：使用no_cache参数或减少缓存TTL
资源清理
- 症状：资源泄漏或连接问题
- 解决方案：确保使用 SIGTERM 或 SIGINT 正确关闭

项目结构

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

贡献

欢迎贡献代码！欢迎提交 Pull 请求。

执照

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。

KVM MCP Server

Integrations