KVM MCP Server

KVM MCP服务器

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

为什么是这个项目？

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

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

特性

• VM生命周期管理:

- 使用可定制的参数创建新的虚拟机 - 启动/停止/重新启动虚拟机 - 列出所有可用的虚拟机及其状态 - 自动状态跟踪和恢复

• 网络管理:

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

• 存储管理:

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

• 显示管理:

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

• 安装支持:

- 从ISO映像安装网络 - 从CDROM进行本地安装 - 支持各种操作系统变体 - 自动安装配置

• 性能优化:

- 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

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

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

1. 安装依赖项：

   pip install -r requirements.txt

1. 配置服务器：

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

用法

1. 启动服务器：

   python3 kvm_mcp_server.py

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

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

示例命令

创建新VM

./create_vm.sh

这将使用默认配置创建一个新的VM 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：上一个日志文件（轮换）
• 日志包括计时信息、连接池状态和缓存命中/未命中

性能指标

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

常见问题及解决方法

1. 连接池耗尽

- 症状：响应时间慢或连接错误 - 解决方案：增加 max_connections 在连接池配置中

1. 缓存无效问题

- 症状：VM信息陈旧 - 解决方案：使用 no_cache 参数或减少缓存TTL

1. 资源清理

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

项目结构

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

贡献

欢迎投稿！请随时提交拉取请求。

许可证

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