kvm-mcp

kvm-mcp

2
virtualization

KVM MCP Server is a JSON-RPC server designed to manage KVM virtual machines efficiently. It simplifies VM operations and automates tasks with features like remote control, lifecycle management, and performance optimizations.

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:

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

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

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

Logging Configuration

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:

    git clone https://github.com/yourusername/kvm-mcp.git
cd kvm-mcp

  2. Create and activate a virtual environment:

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

  3. Install dependencies:

    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:

    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

./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

./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

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.