KVM MCP Server

# KVM MCP Server A powerful JSON-RPC server for managing KVM virtual machines through a simple and intuitive interface. This server provides a centralized way to control and monitor your KVM virtual machines using a standardized protocol. ## Why This Project? Managing KVM virtual machines typically requires using multiple command-line tools like `virsh`, `virt-install`, and `qemu-system`. This project aims to: 1. **Simplify VM Management**: Provide a single, unified interface for all VM operations 2. **Enable Remote Control**: Allow remote management of VMs through JSON-RPC 3. **Automate VM Operations**: Make it easy to script and automate VM management tasks 4. **Standardize VM Configuration**: Ensure consistent VM setup across your infrastructure 5. **Optimize Performance**: Implement efficient resource management and caching strategies ## Features - **VM Lifecycle Management**: - Create new VMs with customizable parameters - Start/stop/reboot VMs - List all available VMs with their status - Automatic state tracking and recovery - **Network Management**: - Configure VM networking using bridges - Support for the `brforvms` bridge - Automatic network interface configuration - IP address tracking and management - **Storage Management**: - Configurable VM disk storage location - Support for various disk formats (qcow2) - Configurable disk sizes - Automatic disk cleanup and management - **Display Management**: - VNC support for graphical access - Automatic VNC port assignment - Tools to find and connect to VM displays - Display state tracking and recovery - **Installation Support**: - Network installation from ISO images - Local installation from CDROM - Support for various OS variants - Automated installation configuration - **Performance Optimizations**: - Connection pooling for libvirt to reduce connection overhead - VM information caching for improved responsiveness - Asynchronous processing for better concurrency - Advanced logging for diagnostics and troubleshooting - Graceful shutdown handling for proper resource cleanup - Automatic connection recovery and validation - Rate limiting for API operations - Performance metrics collection ## Performance Benefits ### Connection Pooling - **Reduced Latency**: Eliminates the overhead of repeatedly opening and closing libvirt connections - **Resource Efficiency**: Maintains a pool of reusable connections, reducing system resource usage - **Automatic Recovery**: Detects and replaces dead connections automatically - **Configurable Pool Size**: Adjust the number of connections based on your workload ### Caching - **Faster Response Times**: Reduces repeated queries to libvirt for common operations - **Configurable TTL**: Set cache expiration based on your needs - **Selective Bypass**: Option to bypass cache for operations requiring fresh data - **Automatic Invalidation**: Cache is automatically invalidated when VM states change ### Asynchronous Processing - **Improved Concurrency**: Handle multiple requests simultaneously - **Better Resource Utilization**: Efficient use of system resources - **Non-blocking Operations**: Long-running operations don't block the server - **Graceful Shutdown**: Proper cleanup of resources during shutdown ### Monitoring and Diagnostics - **Structured Logging**: Easy-to-parse log format for analysis - **Performance Metrics**: Track operation timing and resource usage - **Error Tracking**: Detailed error logging for troubleshooting - **Resource Monitoring**: Track connection pool usage and cache effectiveness ## Configuration The server uses a JSON configuration file (`config.json`) to store default values and paths. This makes the server more portable and easier to customize. The configuration includes: ```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 } } } ``` You can modify these values to match your environment's requirements. The configuration supports environment variable overrides using the following format: - `VM_DISK_PATH` for `disk_path` - `VM_DEFAULT_ISO` for `default_iso` - `VM_DEFAULT_MASTER_IMAGE` for `default_master_image` - `VM_DEFAULT_NAME` for `default_name` - `VM_DEFAULT_MEMORY` for `default_memory` - `VM_DEFAULT_VCPUS` for `default_vcpus` - `VM_DEFAULT_DISK_SIZE` for `default_disk_size` - `VM_DEFAULT_OS_VARIANT` for `default_os_variant` - `VM_DEFAULT_NETWORK` for `default_network` - `VM_IGNITION_DEFAULT_HOSTNAME` for `ignition.default_hostname` - `VM_IGNITION_DEFAULT_USER` for `ignition.default_user` - `VM_IGNITION_DEFAULT_SSH_KEY` for `ignition.default_ssh_key` - `VM_IGNITION_DEFAULT_TIMEZONE` for `ignition.default_timezone` - `VM_IGNITION_DEFAULT_LOCALE` for `ignition.default_locale` - `VM_IGNITION_DEFAULT_PASSWORD_HASH` for `ignition.default_password_hash` ## Performance Tuning ### Connection Pool Configuration ```python 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 ) ``` ### Cache Configuration ```python vm_info_cache = VMInfoCache( max_size=50, # Maximum number of VMs to cache ttl=60 # Time-to-live for cache entries (seconds) ) ``` ### Logging Configuration ```python 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() ] ) ``` ## Getting Started ### Prerequisites - Python 3.6 or higher - KVM and libvirt installed on the host system - The network bridge configured (default: `brforvms`) - VM storage directory created (default: `/vm/`) - Sufficient system resources for your VM workload ### Installation 1. Clone this repository: ```bash git clone https://github.com/yourusername/kvm-mcp.git cd kvm-mcp ``` 2. Create and activate a virtual environment: ```bash python3 -m venv .venv source .venv/bin/activate ``` 3. Install dependencies: ```bash pip install -r requirements.txt ``` 4. Configure the server: - Edit `config.json` to match your environment - Ensure all required directories exist - Verify network bridge configuration - Adjust performance settings as needed ### Usage 1. Start the server: ```bash python3 kvm_mcp_server.py ``` 2. Send commands using JSON-RPC. Example scripts are provided: - `create_vm.sh`: Create a new VM using default configuration - `get_vnc_ports.sh`: Find VNC ports for running VMs ## Example Commands ### Create a New VM ```bash ./create_vm.sh ``` This will create a new VM using the default configuration from `config.json`. You can override any of these defaults by providing them in the request. ### Find VNC Ports ```bash ./get_vnc_ports.sh ``` This will show all running VMs and their VNC ports, making it easy to connect to their displays. ### List VMs with Cache Bypass ```bash echo '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "list_vms", "arguments": {"no_cache": true}}, "id": 1}' | python3 kvm_mcp_server.py ``` ## Monitoring and Troubleshooting ### Log Files - `kvm_mcp.log`: Current log file - `kvm_mcp.log.1`: Previous log file (rotated) - Logs include timing information, connection pool status, and cache hits/misses ### Performance Metrics - Connection pool usage statistics - Cache hit/miss ratios - Operation timing metrics - Resource utilization statistics ### Common Issues and Solutions 1. **Connection Pool Exhaustion** - Symptom: Slow response times or connection errors - Solution: Increase `max_connections` in the connection pool configuration 2. **Cache Invalidation Issues** - Symptom: Stale VM information - Solution: Use `no_cache` parameter or reduce cache TTL 3. **Resource Cleanup** - Symptom: Resource leaks or connection issues - Solution: Ensure proper shutdown using SIGTERM or SIGINT ## Project Structure - `kvm_mcp_server.py`: Main server implementation - `config.json`: Configuration file - `requirements.txt`: Python dependencies - Example scripts in the root directory - Test suite in the `tests/` directory ## Contributing Contributions are welcome! Please feel free to submit a Pull Request. ## License This project is licensed under the MIT License - see the LICENSE file for details.