KVM MCP 服务器

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

为什么要开展这个项目？

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

1. 简化虚拟机管理：为所有虚拟机操作提供单一、统一的界面

2. 启用远程控制：允许通过 JSON-RPC 远程管理虚拟机

3. 自动化虚拟机操作：轻松编写脚本并自动化虚拟机管理任务

4. 标准化虚拟机配置：确保整个基础架构中的虚拟机设置一致

5. 优化性能：实施高效的资源管理和缓存策略

Related MCP server: Model Coupling Platform Server

特征

• 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/ ）

• 为您的虚拟机工作负载提供足够的系统资源

安装

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 ：使用默认配置创建新的虚拟机

   • 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 ：上一个日志文件（已轮换）

• 日志包括时间信息、连接池状态和缓存命中/未命中

绩效指标

• 连接池使用情况统计

• 缓存命中/未命中率

• 操作时序指标

• 资源利用率统计

常见问题和解决方案

1. 连接池耗尽

   • 症状：响应时间缓慢或连接错误

   • 解决方案：增加连接池配置中的max_connections

2. 缓存失效问题

   • 症状：虚拟机信息过时

   • 解决方案：使用no_cache参数或减少缓存TTL

3. 资源清理

   • 症状：资源泄漏或连接问题

   • 解决方案：确保使用 SIGTERM 或 SIGINT 正确关闭

项目结构

• kvm_mcp_server.py ：主服务器实现

• config.json ：配置文件

• requirements.txt ：Python 依赖项

• 根目录中的示例脚本

• tests/目录中的测试套件

贡献

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

执照

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