mait.sh1.69.2

Private beta: features and content may change. No warranty; use at your own risk.

Docs / Agent tools (MCP)

MCP Libvirt

Let an authorized assistant inspect and manage virtual machines, storage and networks on a libvirt host.

For cross-platform testers, systems engineers, and agents that need real guest operating systems.

Read from the top for the basics; the later sections go deeper.

Beta
All components

What it doesBasics

  • Template-based domain creation
  • Lifecycle and snapshot operations
  • Storage-pool management
  • VNC and console endpoint discovery with key input
  • Seven guest templates subject to host and media prerequisites

First useBasics

  1. Identify an owned evaluation VM and inspect its state before a lifecycle change.
  2. Create or branch a domain with explicit resources.
  3. Operate and verify it through the matching guest runbook.

Everyday tasksEveryday use

Clone a disposable VM from a protected base

Repeated tests need consistent guests without modifying the tuned reference machine.

  1. Connect and inspect host capacity.
  2. Identify or adopt the intended base and verify its protected role.
  3. Create an independent clone with explicit compute and storage intent.
  4. Start and validate the clone through its console or remote-access endpoint.
  5. Delete the disposable clone through the owned-resource cleanup path.

What you getTests run on an independently disposable guest while the base remains protected.

How to check: Base and clone identities, ownership records, lifecycle results, and final resource inventory.

Branch a VM from a known snapshot

A test needs to revisit a known point in time and diverge without destroying sibling history.

  1. Inspect the domain and snapshot tree.
  2. Confirm the source snapshot and backing-chain state.
  3. Create a named branch from the selected snapshot.
  4. Run the divergent test and capture its resulting state.
  5. Retain or merge/delete overlays only through the guarded snapshot workflow.

What you getThe VM gains a separate test timeline while the source snapshot and sibling branches remain understandable.

How to check: Snapshot tree before and after, branch identity, domain state, and overlay-aware deletion result.

Settings to decideAdvanced

Connection scope
Give each libvirt endpoint a stable connection slot and verify its URI before creating or adopting resources.
Resource ownership
Operate on session-owned resources by default; adopt existing infrastructure explicitly and use unmanaged visibility only for inspection.
Guest template and lifecycle phase
Select a supported guest family and distinguish installation from runtime device configuration.
Capacity and storage
Inspect host memory, CPU capability, storage pool, format, and backing-chain implications before provisioning.
Virsh passthrough
Enable passthrough only when needed; it runs under the same ownership and destructive-operation guards.

CommandsAdvanced

$ mcp-libvirt version
$ mcp-libvirt serve
$ tools/list # expect 63 tools
$ mcp-libvirt cli domain list # [] is expected before adoption
$ resources/read({"uri":"libvirt://templates"})

Problems and fixesHelp

What you seeCheckFix
A connection slot cannot be created.Validate the URI, daemon reachability, authentication, and host libvirt service.Correct the external connection prerequisite before registering the slot.
A mutation is refused for an existing resource.List tracked and unmanaged resources and confirm the connection slot.Adopt the exact resource intentionally, or leave it unmanaged and continue read-only inspection.
A domain will not start despite being defined.Inspect protected-base role, host capabilities, device dependencies, and guest networking.Use a clone for protected bases; satisfy the missing host prerequisite or choose a supported template/network mode.
A snapshot or volume cleanup is blocked.Inspect backing-chain relationships, attached volumes, children, and whether the target is active.Choose the guarded merge/cascade behavior and detach in-use storage before deletion.
What you see
A connection slot cannot be created.
Check
Validate the URI, daemon reachability, authentication, and host libvirt service.
Fix
Correct the external connection prerequisite before registering the slot.
What you see
A mutation is refused for an existing resource.
Check
List tracked and unmanaged resources and confirm the connection slot.
Fix
Adopt the exact resource intentionally, or leave it unmanaged and continue read-only inspection.
What you see
A domain will not start despite being defined.
Check
Inspect protected-base role, host capabilities, device dependencies, and guest networking.
Fix
Use a clone for protected bases; satisfy the missing host prerequisite or choose a supported template/network mode.
What you see
A snapshot or volume cleanup is blocked.
Check
Inspect backing-chain relationships, attached volumes, children, and whether the target is active.
Fix
Choose the guarded merge/cascade behavior and detach in-use storage before deletion.

All MCP Libvirt problems and fixes →

Good to knowHelp

  • Existing host resources become manageable once adopted, and session ownership gates mutation.
  • Ending a session keeps its resources; adopt them again to manage them.
  • Screenshots come from a related viewer such as MCP VNC.