Powerful MCP JSON-RPC server for centralized KVM virtual machine management offering VM lifecycle control, network and storage configuration, VNC display access, installation automation, and optimized performance through connection pooling, caching, and asynchronous processing.
Unlock the full potential of KVM MCP Server through LangDB's AI Gateway. Get enterprise-grade security, analytics, and seamless integration with zero configuration.
Free tier available • No credit card required
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.
Managing KVM virtual machines typically requires using multiple command-line tools like virsh
, virt-install
, and qemu-system
. This project aims to:
VM Lifecycle Management:
Network Management:
brforvms
bridgeStorage Management:
Display Management:
Installation Support:
Performance Optimizations:
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
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() ] )
brforvms
)/vm/
)Clone this repository:
git clone https://github.com/yourusername/kvm-mcp.git cd kvm-mcp
Create and activate a virtual environment:
python3 -m venv .venv source .venv/bin/activate
Install dependencies:
pip install -r requirements.txt
Configure the server:
config.json
to match your environmentStart the server:
python3 kvm_mcp_server.py
Send commands using JSON-RPC. Example scripts are provided:
create_vm.sh
: Create a new VM using default configurationget_vnc_ports.sh
: Find VNC ports for running VMs./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.
./get_vnc_ports.sh
This will show all running VMs and their VNC ports, making it easy to connect to their displays.
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
: Current log filekvm_mcp.log.1
: Previous log file (rotated)Connection Pool Exhaustion
max_connections
in the connection pool configurationCache Invalidation Issues
no_cache
parameter or reduce cache TTLResource Cleanup
kvm_mcp_server.py
: Main server implementationconfig.json
: Configuration filerequirements.txt
: Python dependenciestests/
directoryContributions are welcome! Please feel free to submit a Pull Request.
This project is licensed under the MIT License - see the LICENSE file for details.
Discover shared experiences
Shared threads will appear here, showcasing real-world applications and insights from the community. Check back soon for updates!