Servidor KVM MCP

Un potente servidor JSON-RPC para gestionar máquinas virtuales KVM mediante una interfaz sencilla e intuitiva. Este servidor proporciona una forma centralizada de controlar y supervisar sus máquinas virtuales KVM mediante un protocolo estandarizado.

¿Por qué este proyecto?

La gestión de máquinas virtuales KVM suele requerir el uso de varias herramientas de línea de comandos como virsh , virt-install y qemu-system . Este proyecto tiene como objetivo:

Simplifique la administración de máquinas virtuales : proporcione una interfaz única y unificada para todas las operaciones de máquinas virtuales
Habilitar control remoto : permite la administración remota de máquinas virtuales a través de JSON-RPC
Automatice las operaciones de VM : facilite la creación de scripts y la automatización de tareas de administración de VM
Estandarizar la configuración de VM : garantizar una configuración de VM consistente en toda su infraestructura
Optimizar el rendimiento : implementar estrategias eficientes de gestión de recursos y almacenamiento en caché

Características

Gestión del ciclo de vida de las máquinas virtuales :
- Cree nuevas máquinas virtuales con parámetros personalizables
- Iniciar/detener/reiniciar máquinas virtuales
- Enumere todas las máquinas virtuales disponibles con su estado
- Seguimiento y recuperación automáticos del estado
Gestión de red :
- Configurar la red de máquinas virtuales mediante puentes
- Soporte para el puente brforvms
- Configuración automática de la interfaz de red
- Seguimiento y gestión de direcciones IP
Gestión de almacenamiento :
- Ubicación de almacenamiento del disco de VM configurable
- Compatibilidad con varios formatos de disco (qcow2)
- Tamaños de disco configurables
- Limpieza y gestión automática del disco
Gestión de pantalla :
- Compatibilidad con VNC para acceso gráfico
- Asignación automática de puerto VNC
- Herramientas para buscar y conectarse a pantallas de máquinas virtuales
- Seguimiento y recuperación del estado de la pantalla
Soporte de instalación :
- Instalación de red desde imágenes ISO
- Instalación local desde CDROM
- Compatibilidad con varias variantes del sistema operativo
- Configuración de instalación automatizada
Optimizaciones de rendimiento :
- Agrupación de conexiones para libvirt para reducir la sobrecarga de conexión
- Almacenamiento en caché de información de VM para una mejor capacidad de respuesta
- Procesamiento asincrónico para una mejor concurrencia
- Registro avanzado para diagnóstico y resolución de problemas
- Manejo elegante del apagado para una limpieza adecuada de los recursos
- Recuperación y validación automática de la conexión
- Limitación de velocidad para operaciones de API
- Recopilación de métricas de rendimiento

Beneficios de rendimiento

Agrupación de conexiones

Latencia reducida : elimina la sobrecarga de abrir y cerrar repetidamente las conexiones de libvirt
Eficiencia de recursos : mantiene un grupo de conexiones reutilizables, lo que reduce el uso de recursos del sistema.
Recuperación automática : detecta y reemplaza conexiones inactivas automáticamente
Tamaño de grupo configurable : ajuste la cantidad de conexiones según su carga de trabajo

Almacenamiento en caché

Tiempos de respuesta más rápidos : reduce las consultas repetidas a libvirt para operaciones comunes
TTL configurable : configure la expiración de la caché según sus necesidades
Bypass selectivo : opción para omitir el caché para operaciones que requieren datos nuevos
Invalidación automática : la caché se invalida automáticamente cuando cambian los estados de la máquina virtual.

Procesamiento asincrónico

Concurrencia mejorada : maneja múltiples solicitudes simultáneamente
Mejor utilización de recursos : uso eficiente de los recursos del sistema
Operaciones sin bloqueo : las operaciones de larga duración no bloquean el servidor.
Apagado elegante : limpieza adecuada de recursos durante el apagado

Monitoreo y diagnóstico

Registro estructurado : formato de registro fácil de analizar para su análisis
Métricas de rendimiento : Realice un seguimiento del tiempo de operación y el uso de recursos
Seguimiento de errores : registro detallado de errores para la resolución de problemas
Monitoreo de recursos : realice un seguimiento del uso del grupo de conexiones y la efectividad de la caché

Configuración

El servidor utiliza un archivo de configuración JSON ( config.json ) para almacenar los valores y rutas predeterminados. Esto facilita su portabilidad y personalización. La configuración incluye:

{
    "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
        }
    }
}

Puede modificar estos valores para que se ajusten a los requisitos de su entorno. La configuración admite la anulación de variables de entorno con el siguiente formato:

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

Ajuste del rendimiento

Configuración del grupo de conexiones

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
)

Configuración de caché

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

Configuración de registro

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()
    ]
)

Empezando

Prerrequisitos

Python 3.6 o superior
KVM y libvirt instalados en el sistema host
El puente de red configurado (predeterminado: brforvms )
Directorio de almacenamiento de VM creado (predeterminado: /vm/ )
Recursos del sistema suficientes para la carga de trabajo de su máquina virtual

Instalación

Clonar este repositorio:
git clone https://github.com/yourusername/kvm-mcp.git cd kvm-mcp
Crear y activar un entorno virtual:
python3 -m venv .venv source .venv/bin/activate
Instalar dependencias:
pip install -r requirements.txt
Configurar el servidor:
- Edite config.json para que coincida con su entorno
- Asegúrese de que existan todos los directorios necesarios
- Verificar la configuración del puente de red
- Ajuste la configuración de rendimiento según sea necesario

Uso

Iniciar el servidor:
python3 kvm_mcp_server.py
Envíe comandos mediante JSON-RPC. Se proporcionan scripts de ejemplo:
- create_vm.sh : crea una nueva máquina virtual usando la configuración predeterminada
- get_vnc_ports.sh : Encuentra puertos VNC para máquinas virtuales en ejecución

Comandos de ejemplo

Crear una nueva máquina virtual

./create_vm.sh

Esto creará una nueva máquina virtual con la configuración predeterminada de config.json . Puede anular cualquiera de estos valores predeterminados proporcionándolos en la solicitud.

Encontrar puertos VNC

./get_vnc_ports.sh

Esto mostrará todas las máquinas virtuales en ejecución y sus puertos VNC, lo que facilitará la conexión a sus pantallas.

Lista de máquinas virtuales con omisión de caché

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

Monitoreo y resolución de problemas

Archivos de registro

kvm_mcp.log : archivo de registro actual
kvm_mcp.log.1 : Archivo de registro anterior (rotado)
Los registros incluyen información de tiempo, estado del grupo de conexiones y aciertos y errores de caché.

Métricas de rendimiento

Estadísticas de uso del pool de conexiones
Tasas de aciertos y errores de caché
Métricas de tiempo de operación
Estadísticas de utilización de recursos

Problemas comunes y soluciones

Agotamiento del pool de conexiones
- Síntoma: Tiempos de respuesta lentos o errores de conexión
- Solución: Aumente max_connections en la configuración del grupo de conexiones
Problemas de invalidación de caché
- Síntoma: Información de máquina virtual obsoleta
- Solución: utilice el parámetro no_cache o reduzca el TTL de la caché
Limpieza de recursos
- Síntoma: Fugas de recursos o problemas de conexión
- Solución: Asegúrese de que el apagado sea correcto utilizando SIGTERM o SIGINT

Estructura del proyecto

kvm_mcp_server.py : Implementación del servidor principal
config.json : Archivo de configuración
requirements.txt : Dependencias de Python
Scripts de ejemplo en el directorio raíz
Conjunto de pruebas en el directorio tests/

Contribuyendo

¡Agradecemos sus contribuciones! No dude en enviar una solicitud de incorporación de cambios.

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.

KVM MCP Server

Integrations