LI
AI & ML

Libvirt MCP Server for VM Lifecycle Management

Manage virtual machines with an MCP server that lets an LLM interact with libvirt to create, destroy, and list VMs for full lifecycle control.

View on GitHub
Quick Install
npx -y @MatiasVara/libvirt-mcp

Overview

Libvirt MCP Server exposes libvirt-managed virtual machine lifecycle operations through an MCP-compatible server interface so large language models (LLMs) and other automation agents can create, inspect, and destroy VMs programmatically. By bridging libvirt with a lightweight MCP server, you can delegate VM lifecycle tasks to an LLM-based agent or integrate VM management into higher-level orchestration workflows without embedding libvirt bindings in those agents.

This server is useful when you need ephemeral development or test environments, automated provisioning for CI jobs, or on-demand sandbox instantiation from an AI assistant. The server centralizes libvirt access and provides a small, predictable API surface that an LLM can call (using MCP-style tool invocations) to perform domain management while the server enforces libvirt access, logging, and host-level policies.

Features

  • Exposes VM lifecycle operations through a machine-callable MCP interface
  • Create, start, shutdown, reboot, and destroy virtual machines
  • List domains and retrieve domain metadata and status
  • Parameterized VM creation (name, CPU, memory, disk, network)
  • Dry-run / validation mode to check VM templates before instantiation
  • Audit logging of requests and domain state changes
  • Configurable libvirt connection (system/session/remote)
  • Optional authentication and access controls for tool use

Installation / Configuration

Prerequisites:

  • libvirt installed and configured on the host (qemu/kvm for Linux)
  • golang toolchain (if building from source) or a prebuilt binary release
  • git

Clone and build (example using Go):

git clone https://github.com/MatiasVara/libvirt-mcp.git
cd libvirt-mcp
# build binary (if the project is Go-based)
go build -o libvirt-mcp ./cmd/libvirt-mcp

Run the server locally with minimum options:

# Example: connect to the local system libvirt instance and listen on port 8080
./libvirt-mcp --libvirt-uri=qemu:///system --port=8080

Configuration via environment variables (examples):

export LIBVIRT_URI="qemu:///system"   # libvirt connection URI
export MCP_BIND_ADDR="0.0.0.0:8080"   # address the MCP server binds to
export MCP_AUTH_TOKEN="s3cr3ttoken"   # optional bearer token for API calls
./libvirt-mcp

Systemd unit (example) — run on machine startup:

[Unit]
Description=Libvirt MCP Server
After=network.target

[Service]
ExecStart=/usr/local/bin/libvirt-mcp --libvirt-uri=qemu:///system --port=8080
Restart=on-failure
User=libvirtmcp

[Install]
WantedBy=multi-user.target

Adjust memory, CPU, and disk defaults in the server configuration file or by passing flags when creating VMs.

Available Tools / Resources

The server exposes a small set of tool-like RPC endpoints designed to be invoked by an LLM agent. Typical endpoints and parameters:

  • create_vm
    • Parameters: name, memory_mb, vcpus, disk_gb, network, cloud_init_userdata (optional), image_template
    • Returns: domain_name, uuid, status, domain_xml (generated)
  • list_vms
    • Parameters: show_all (bool)
    • Returns: list of {name, uuid, state, cpu, memory}
  • get_vm_info
    • Parameters: name_or_uuid
    • Returns: detailed domain info (XML, current state, resources)
  • start_vm
    • Parameters: name_or_uuid
    • Returns: status
  • shutdown_vm / force_destroy_vm
    • Parameters: name_or_uuid, timeout_seconds (optional)
    • Returns: status
  • validate_template
    • Parameters: domain_spec (same fields as create_vm)
    • Returns: validation_result, warnings

Example curl call (create VM):

curl -X POST http://localhost:8080/mcp/create_vm \
  -H "Authorization: Bearer s3cr3ttoken" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ai-test-001",
    "memory_mb": 2048,
    "vcpus": 2,
    "disk_gb": 20,
    "image_template": "ubuntu-22.04-cloudimg.qcow2",
    "cloud_init_userdata": "#cloud-config\npackages: [htop]\n"
  }'

Example response (JSON):

{
  "domain_name": "ai-test-001",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "status": "running",
  "domain_xml": "<domain>...</domain>"
}

Use Cases

  • LLM-driven test harness: An LLM agent can spin up an ephemeral VM, run a test workload, collect logs, and destroy the VM when finished. This avoids persistent test artifacts on the host.
  • On-demand developer sandboxes: Developers or an assistant request a VM with specific resources and software via natural language; the assistant calls create_vm and returns access details.
  • CI job isolation: A CI pipeline can request isolated VMs from the MCP server for untrusted build jobs and automatically tear them down after completion.
  • Classroom / workshop environments: Provision and destroy student VMs dynamically, allowing an LLM tutor to create per-student lab instances.
  • Reproducible environment snapshots: Use validate_template and create_vm to produce consistent test environments from stored templates and cloud-init snippets.

Notes and Best Practices

  • Run the MCP server on a host with appropriate security boundaries; granting libvirt access provides powerful capabilities.
  • Use authentication and network restrictions to limit who can call lifecycle tools.
  • Prefer dry-run/validate calls before provisioning large or persistent disks to avoid
Tags:ai-ml