KVM

You operate a KVM MCP Server to manage virtual machines via a centralized, programmable interface. It exposes a JSON-RPC style workflow that lets you create, start, stop, and monitor KVM VMs, configure networking and storage, and automate installation and maintenance tasks from a consistent, scriptable endpoint.

How to use

You will run the MCP server locally and interact with it through a client that calls the available endpoints. Typical usage patterns include creating new VMs with a default configuration, starting or stopping existing VMs, querying VM status, and retrieving VNC display information for graphical access. You can script common workflows, such as provisioning a VM, attaching storage, configuring networking, and initiating automated OS installations, all through a unified API.

How to install

Prerequisites: you need Python 3.6 or higher, KVM and libvirt installed on the host, a configured network bridge (default brforvms), and a VM storage directory created (default /vm/). Ensure you have sufficient system resources for your workload.

Step 1. Clone the MCP server repository to your host.

Step 2. Create and activate a virtual environment.

Step 3. Install dependencies from the requirements file.

Step 4. Prepare configuration and start the server.

Step 5. Run the server using the recommended local command.

Configuration

Configuration is stored in a JSON file named config.json and provides default values and paths for VM creation, networking, storage, and Fedora CoreOS ignition settings. You can adjust these values to fit your environment.

{
  "vm": {
    "disk_path": "/vm",
    "default_iso": "/iso/ubuntu-24.04.2-live-server-amd64.iso",
    "default_master_image": "/iso/fedora-coreos-41-qemu.x86_64.qcow2",
    "default_name": "newvmname",
    "default_memory": 2048,
    "default_vcpus": 2,
    "default_disk_size": 20,
    "default_os_variant": "generic",
    "default_network": "brforvms",
    "ignition": {
      "default_hostname": "coreos",
      "default_user": "core",
      "default_ssh_key": "~/.ssh/id_rsa.pub",
      "default_timezone": "UTC",
      "default_locale": "en_US.UTF-8",
      "default_password_hash": null
    }
  }
}

Environment variables

You can override configuration values via environment variables using the following mappings. This makes the server portable across environments without editing the config file directly.

{
  "VM_DISK_PATH": "/vm",
  "VM_DEFAULT_ISO": "/iso/ubuntu-24.04.2-live-server-amd64.iso",
  "VM_DEFAULT_MASTER_IMAGE": "/iso/fedora-coreos-41-qemu.x86_64.qcow2",
  "VM_DEFAULT_NAME": "newvmname",
  "VM_DEFAULT_MEMORY": 2048,
  "VM_DEFAULT_VCPUS": 2,
  "VM_DEFAULT_DISK_SIZE": 20,
  "VM_DEFAULT_OS_VARIANT": "generic",
  "VM_DEFAULT_NETWORK": "brforvms",
  "VM_IGNITION_DEFAULT_HOSTNAME": "coreos",
  "VM_IGNITION_DEFAULT_USER": "core",
  "VM_IGNITION_DEFAULT_SSH_KEY": "~/.ssh/id_rsa.pub",
  "VM_IGNITION_DEFAULT_TIMEZONE": "UTC",
  "VM_IGNITION_DEFAULT_LOCALE": "en_US.UTF-8",
  "VM_IGNITION_DEFAULT_PASSWORD_HASH": null
}

Getting started with development and troubleshooting

Run the server locally with Python and monitor logs to troubleshoot issues. The server exposes performance metrics, structured logs, and resource usage traces to aid diagnostics.

Monitoring and troubleshooting

Review the server logs for timing, connection pool status, and cache effectiveness. Use the provided metrics to tune performance, diagnose failures, and ensure proper shutdown handling to avoid resource leaks.

Notes

Keep the VM storage directory and bridge configuration in sync with your host environment. Use the default brforvms bridge unless you need a custom networking setup. Ensure you have sufficient resources for the VMs you plan to run.

Security considerations

Limit access to the MCP server to trusted clients. Consider network segmentation and firewall rules around the host to minimize exposure of the management interface.

Tools and endpoints

The MCP server exposes a set of capabilities for VM lifecycle, networking, storage, display, and installation management. Use the MCP client to call these endpoints and automate routine VM operations.

Available tools

VM lifecycle

Manage VM creation, start, stop, and reboot operations with automatic state tracking.

Network management

Configure VM networking, bridges, and IP tracking for VMs.

Display management

Provide VNC access and display tracking for VMs.