ovirt-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
ovirt-mcp: Enterprise Virtualization Manager for AI Agents
Modern, production-grade Model Context Protocol (MCP) server for Oracle Linux Virtualization Manager (OLVM) and oVirt hypervisor engines.
ovirt-mcp connects LLMs (Claude, GPT, Llama, Mistral, Ollama) directly to your enterprise virtualization infrastructure with token-optimized responses, deep hardware inspection, audit trails, and multi-layered safety controls.
Table of Contents
Related MCP server: vSphere MCP Server
Features
Fast Inventory (
ovirt_vm_list): Query VMs across clusters with RAM, vCPU, IP addresses, cluster, host, and HA status in milliseconds.Deep Hardware & Policy Inspection (
ovirt_vm_get): Access detailed CPU topology, memory ballooning ceilings, NUMA/IO threads, VirtIO-SCSI multi-queue, affinity groups, affinity labels, BIOS/TPM settings, thin-provisioned disk sizes (actual vs. provisioned), and vNIC bindings.Dual Response Modes (Compact vs. Detailed):
Compact Mode: ~90 tokens per VM (up to 86% token savings), ideal for local and small context window models (Ollama, Mistral 7B, Llama 3 8B).
Detailed Mode: Comprehensive enterprise topology (~650 tokens per VM) for complex engineering tasks with frontier LLMs.
Audit Log Inspection (
ovirt_vm_events): Filter and analyze engine lifecycle events, warnings, failure reasons, and admin actions.Multi-Layer Enterprise Security:
MCP_READ_ONLY=true: Hard block against mutating actions.MCP_SAFE_MODE=true: Requires explicitconfirm=Truefor destructive actions.Recommended least-privilege service account integration.
Automated TLS Management: Automatic engine PKI CA download and certificate caching.
Prerequisites & System Packages
ovirt-mcp is built on Python and the official ovirt-engine-sdk-python library, which requires native C headers for libcurl and libxml2.
Supported Python Versions
Python 3.10, 3.11, or 3.12 (Python 3.12 recommended).
Required OS Packages
Before creating your Python virtual environment, install the required development headers:
Debian / Ubuntu / Proxmox
sudo apt-get update
sudo apt-get install -y python3-venv python3-dev libcurl4-openssl-dev libxml2-dev gcc build-essentialOracle Linux / RHEL / Rocky / AlmaLinux / CentOS Stream
sudo dnf install -y python3-devel libcurl-devel libxml2-devel gccStep-by-Step Installation Guide
Step 1: Clone the Repository
git clone https://github.com/gerilab/ovirt-mcp.git
cd ovirt-mcpStep 2: Create and Activate Virtual Environment
Always use an isolated virtual environment to prevent package version conflicts:
python3 -m venv .venv
source .venv/bin/activateVerify that Python and pip are up to date:
pip install --upgrade pipStep 3: Install ovirt-mcp and Dependencies
For Standard Production Deployment:
pip install -e .For Development and Testing (includes pytest, ruff, mypy):
pip install -e ".[dev]"Configuration (.env) Reference
Create your local .env configuration file from the template:
cp .env.example .env
chmod 600 .envEdit .env with your preferred editor:
# ── oVirt / OLVM Engine Connection ──────────────────────────────────────────
OVIRT_URL=https://olvm-engine.example.com/ovirt-engine/api
OVIRT_USERNAME=admin@internal
OVIRT_PASSWORD=YourSecurePasswordHere
# ── TLS / SSL Certificate Security ──────────────────────────────────────────
# Set to true for lab or test environments using self-signed certificates
OVIRT_INSECURE=false
# Path to CA certificate (leave blank to auto-download from the engine PKI endpoint)
OVIRT_CA_FILE=
# ── Connection Resiliency ───────────────────────────────────────────────────
OVIRT_TIMEOUT=30
OVIRT_MAX_RETRIES=3
# ── Logging & Security Policies ─────────────────────────────────────────────
MCP_LOG_LEVEL=INFO
MCP_SAFE_MODE=true
MCP_READ_ONLY=false
# ── Response Optimization (Token Economics) ──────────────────────────────────
# When true, ovirt_vm_get returns compact summaries by default (~86% fewer tokens)
MCP_COMPACT_MODE=falseConfiguration Options Breakdown
Parameter | Type | Default | Description |
| string | required | Full REST API URL to your engine (must end with |
| string | required | Engine username including profile suffix (see AAA Profiles below). |
| string | required | Engine account password. |
| bool |
| When |
| path |
| Path to PEM CA certificate. If omitted, engine CA is downloaded automatically. |
| int |
| Network request timeout in seconds. |
| int |
| Connection retry count with exponential backoff. |
| bool |
| When |
| bool |
| When |
| bool |
| Default format for |
Authentication & AAA Profiles (Crucial)
oVirt and OLVM use an internal authentication provider that requires the profile name as part of the username.
Default Administrator Account: In OLVM and oVirt 4.5+, the internal superuser account is typically:
admin@internal(User:
admin@ovirt, Profile:internal). Passing onlyadmin@ovirtoradmin@internalwill produceNo valid profile found in credentialsorInvalid user credentials.LDAP / Active Directory Accounts: Formatted as
username@domain.commatching the external domain name configured in the engine.
Service Account Best Practices
For production environments,do not use full administrative superuser credentials. Create a dedicated, restricted service account for the AI Agent:
In the oVirt/OLVM Administration Portal, navigate to Administration → Configure → Roles.
For read-only monitoring: Assign the built-in
ReadOnlyAdminrole to a new usermcp-agent@internal.For VM operations (start/stop/reboot): Assign the
UserVmManagerorUserVmRunTimePermissionsrole scoped specifically to the designated Cluster or Data Center.Use
mcp-agent@internalin your.env.
TLS & SSL Certificate Management
By default, ovirt-mcp automatically downloads the engine root CA certificate from:
https://<engine-host>/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CAThe downloaded CA is safely cached in your local environment, ensuring secure TLS verification without manual certificate handling.
For air-gapped systems: specify
OVIRT_CA_FILE=/path/to/ca.pem.For quick local lab experiments: set
OVIRT_INSECURE=true.
Operational Modes
Compact vs. Detailed Mode (Token Optimization)
Different LLMs have different context window sizes and token costs. ovirt-mcp provides dual output modes to optimize token consumption:
Mode | Typical Size | Token Estimate | Intended Models / Use Cases |
Compact Mode ( | ~360 bytes | ~90 tokens | Ollama, Mistral 7B, Llama 3 8B, fast triage, inventory checks |
Detailed Mode ( | ~2,600 bytes | ~650 tokens | Claude 3.5 Sonnet, GPT-4o, hardware troubleshooting, capacity planning |
Server-wide default: Set
MCP_COMPACT_MODE=truein.envto make allovirt_vm_getcalls lightweight by default.Per-query override: The calling agent or user can pass
compact=Trueorcompact=Falsedynamically to anyovirt_vm_getcall.
Safe Mode & Mutation Confirmation
To prevent accidental hypervisor outages from hallucinatory or unintended agent actions:
When
MCP_SAFE_MODE=true(the default), mutating operations require an explicitconfirm=Trueparameter.If
confirm=Trueis not provided, the server returns an explicit confirmation request with safety details before taking action.
Read-Only Enforcement
When MCP_READ_ONLY=true is set:
Any action that attempts to modify engine state (stopping VMs, reboots, disk manipulation, etc.) is rejected immediately with
SecurityError: Operation blocked: Server is in READ-ONLY mode.
Hierarchical Naming Convention
To ensure clarity for both AI Agents and human operators, all tools adhere to a strict domain-namespaced naming convention:
ovirt_<domain>_[<subresource>_]<action>ovirt_vm_*: All operations affecting virtual machines (lifecycle, snapshots, disks, media/ISO, migration, guest agent).e.g.
ovirt_vm_list,ovirt_vm_start,ovirt_vm_stop,ovirt_vm_snapshot_create,ovirt_vm_disk_attach,ovirt_vm_migrate.
ovirt_host_*: Hypervisor host operations (list,get,activate,maintenance,restart,stats,upgrade_check,upgrade,nic_list,numa_list,device_list,storage_list,events).ovirt_cluster_*: Cluster topology, compatibility versions, and CPU profiles.ovirt_storage_*: Storage domains and capacity management.ovirt_disk_*: Standalone floating disks and volume operations.ovirt_network_*: Virtual networks and vNIC profiles.
Tool Reference
1. ovirt_test_connection
Validates connectivity to the oVirt / OLVM engine, verifies API credentials, and reports platform version metadata.
Inputs: None
Outputs (
SystemStatus):status: Connection state (connected).product_name: e.g."Oracle Linux Virtualization Manager"or"oVirt Engine".version: Engine version string (e.g."4.5.5-1.66.el8").url: Connected endpoint URL.username: Connected user identity.
Example Output:
{
"status": "connected",
"product_name": "Oracle Linux Virtualization Manager",
"version": "4.5.5-1.66.el8",
"url": "https://olvm-engine.example.com/ovirt-engine/api",
"username": "admin@internal"
}2. ovirt_vm_list
Lists virtual machines with fast status, cluster, host, vCPU, RAM, and reported network addresses.
Inputs:
search(string, optional): oVirt engine search filter (e.g.,"status=up","name=prod*","cluster=DefaultCluster").
Outputs:
list[VmSummary]id: Unique UUID of the VM.name: VM display name.status: Execution state (up,down,powering_up,paused, etc.).cluster_name: Host cluster name.host_name: Current running hypervisor host name (orNoneif stopped).memory_mb: Allocated RAM in megabytes.cpu_cores: Total vCPU count.ip_addresses: List of IPv4 and IPv6 addresses reported by the guest agent.fqdn: Fully qualified domain name reported by guest agent.ha_enabled: High-availability status boolean.
Example Output:
[
{
"id": "571ae214-9b52-431e-bbc8-a09b601c1cd3",
"name": "testvm001",
"status": "down",
"cluster_name": "DefaultCluster",
"host_name": null,
"memory_mb": 18432,
"cpu_cores": 8,
"ip_addresses": [],
"fqdn": null,
"ha_enabled": false
}
]3. ovirt_vm_get
Deep inspection of a single virtual machine by name or UUID. Supports both Compact and Detailed modes.
Inputs:
name_or_id(string, required): VM display name or UUID.compact(bool, optional): Whentrue, returnsVmCompactDetail(~90 tokens); whenfalse, returns comprehensiveVmDetail(~650 tokens). If omitted, uses the server'sMCP_COMPACT_MODEsetting.
Compact Mode Output (VmCompactDetail):
{
"id": "571ae214-9b52-431e-bbc8-a09b601c1cd3",
"name": "testvm001",
"status": "down",
"cluster_name": "DefaultCluster",
"host_name": null,
"memory_mb": 18432,
"cpu_cores": 8,
"ip_addresses": [],
"fqdn": null,
"os_type": "rhel_8x64",
"ha_enabled": false,
"disks_summary": [
"OracleEL8.10-data-disk (100.0 GB)",
"OracleEL8.10-os-disk (40.0 GB)"
],
"nics_count": 1,
"snapshots_count": 1,
"description": "Disaster Recovery Node"
}Detailed Mode Output (VmDetail):
Provides full enterprise virtualization parameters:
cpu: Sockets, cores per socket, threads per core, CPU pinning policy, auto pinning policy, CPU shares.memory: Allocated RAM, guaranteed RAM, maximum balloon ceiling, ballooning state.io_scsi: Dedicated I/O threads, VirtIO-SCSI controller state, multi-queue configuration.affinity_and_placement: Placement policy (migratable,pinned), assigned affinity groups, affinity labels, tags.hardware: BIOS type (i440fx_sea_bios,q35_secure_boot), machine type, display (vnc,spice), TPM device state, delete protection status.disks: List of disks with thin-provisioning metadata (provisioned GB vs. actual storage consumption GB), interface type (virtio,virtio_scsi), disk format (cow,raw), bootable flag, storage domain name.nics: List of virtual network interfaces with interface type, MAC address, network profile, link state, and plugged state.snapshots_count: Number of active snapshots.lifecycle: Creation timestamp, last start/stop timestamp, stop reason, migration downtime.
4. ovirt_vm_events
Retrieves and filters recent audit log events for a specific virtual machine.
Inputs:
name_or_id(string, required): VM display name or UUID.max_events(int, optional, default: 20): Maximum number of events to return.min_severity(string, optional, default: "normal"): Minimum severity filter ("normal","warning","error","alert").
Outputs:
list[VmEvent]id: Event entry ID.code: Engine event numerical code.description: Event message text (includes initiating user, host, and error messages).severity:"normal","warning","error", or"alert".time: Timestamp with timezone.
Example Output:
[
{
"id": "184912",
"code": 61,
"description": "VM testvm001 is down. Exit message: Admin shut down from the engine",
"severity": "normal",
"time": "2026-08-31 23:55:36.883000+02:00"
},
{
"id": "184910",
"code": 73,
"description": "VM shutdown initiated by admin@internal on VM testvm001 (Host: olvmhost003.example.com).",
"severity": "normal",
"time": "2026-08-31 23:53:31.289000+02:00"
}
]5. ovirt_vm_start
Powers on a virtual machine by display name or UUID. Idempotent: if the VM is already up, it reports success immediately without redundant hypervisor calls.
Inputs:
name_or_id(string, required): VM display name or UUID.pause(bool, optional, default: false): Iftrue, boots the VM into paused state.wait(bool, optional, default: false): Iftrue, waits synchronously until the VM reaches theupstate before returning.timeout_seconds(int, optional, default: 60): Maximum time to wait ifwait=true.
Outputs (
VmLifecycleResult):success: Boolean indicating if operation succeeded or was accepted.action:"start".vm_id: VM UUID.vm_name: VM display name.previous_status: Status prior to invocation (e.g."down").current_status: Status after invocation (e.g."powering_up"or"up").message: Human-readable summary.
Example Output:
{
"success": true,
"action": "start",
"vm_id": "2a6c96b7-4da0-422f-8e7c-aa1fd5448144",
"vm_name": "testvm002",
"previous_status": "down",
"current_status": "powering_up",
"message": "VM 'testvm002' start initiated successfully (status: powering_up)."
}6. ovirt_vm_stop
Stops or shuts down a virtual machine. Supports both clean guest-initiated shutdown and hard power-off. Safe-Mode protected: In Safe Mode (MCP_SAFE_MODE=true), requires explicit confirm=True. Idempotent: if already down, reports success immediately.
Boot Readiness Guard: Graceful shutdown (graceful=True) cannot execute if the virtual machine is currently booting (powering_up, wait_for_launch, or reboot_in_progress). At this boot stage, the guest operating system kernel and guest agent (qemu-guest-agent / vtools) have not finished initializing, making ACPI/vtools signals ineffective. ovirt_vm_stop validates boot readiness and will raise an error instructing the caller to wait until the VM is up, or specify graceful=False for an immediate hard power-off.
Inputs:
name_or_id(string, required): VM display name or UUID.graceful(bool, optional, default: true):true(Default): Initiates a clean, orderly shutdown of the operating system inside the guest through the oVirt / QEMU Guest Agent (vtools) and ACPI. Services terminate properly and filesystem caches flush to disk.false: Executes an immediate hard power-off (pulling the virtual plug / force kill). Use only when the guest OS is hung or unresponsive.
force(bool, optional, default: false): Iftrue, forces stop even if a backup is active.confirm(bool, optional, default: false): Explicit confirmation required whenMCP_SAFE_MODE=true.wait(bool, optional, default: false): Iftrue, blocks synchronously until the VM reachesdownstate.timeout_seconds(int, optional, default: 60): Maximum wait duration.
Outputs (
VmLifecycleResult):success: Boolean indicating if shutdown/stop succeeded.action:"shutdown"or"stop".vm_id: VM UUID.vm_name: VM display name.previous_status: Status prior to stop.current_status: Status after initiation ("powering_down"or"down").graceful:trueif initiated via guest agent (vtools) / ACPI;falseif hard power-off.message: Human-readable summary.
Example Output (Graceful Stop via vtools):
{
"success": true,
"action": "shutdown",
"vm_id": "2a6c96b7-4da0-422f-8e7c-aa1fd5448144",
"vm_name": "testvm002",
"previous_status": "up",
"current_status": "powering_down",
"graceful": true,
"message": "VM 'testvm002' graceful shutdown initiated via guest agent (vtools) / ACPI (status: powering_down)."
}7. ovirt_vm_shutdown
Dedicated tool for initiating a clean, graceful shutdown of the operating system inside the guest VM via guest tools (vtools / QEMU guest agent) and ACPI. This is an alias for ovirt_vm_stop(graceful=True).
Inputs:
name_or_id(string, required): VM display name or UUID.force(bool, optional, default: false): Force shutdown even if backup is active.confirm(bool, optional, default: false): Explicit confirmation required whenMCP_SAFE_MODE=true.wait(bool, optional, default: false): Blocks synchronously untildownstate.timeout_seconds(int, optional, default: 60): Maximum wait duration.
8. ovirt_vm_reboot
Reboots a running virtual machine. Safe-Mode protected: requires explicit confirm=True. Rejects reboots if the VM is currently down with a helpful recommendation to use ovirt_vm_start.
Inputs:
name_or_id(string, required): VM display name or UUID.force(bool, optional, default: false): Force reboot even if a backup is active.confirm(bool, optional, default: false): Explicit confirmation required whenMCP_SAFE_MODE=true.wait(bool, optional, default: false): Iftrue, blocks until VM completes restart cycle and returns toupstate.timeout_seconds(int, optional, default: 60): Maximum wait duration.
Outputs (
VmLifecycleResult):success: Boolean indicating if reboot was initiated.action:"reboot".vm_id: VM UUID.vm_name: VM display name.previous_status: Status prior to reboot.current_status:"rebooting"or"up".message: Human-readable summary.
9. ovirt_vm_create
Provisions a new virtual machine in oVirt / OLVM. Supports creation from the standard Blank template or existing OS templates, along with CPU, RAM, primary disk provisioning, and vNIC profiles.
Inputs:
name(string, required): Unique name for the virtual machine.cluster(string, required): Cluster name or UUID.template(string, optional, default: "Blank"): Base template name or UUID.memory_mb(int, optional, default: 2048): RAM allocation in megabytes.cpu_cores(int, optional, default: 1): vCPU cores per socket.cpu_sockets(int, optional, default: 1): CPU sockets count.description(string, optional): Comment or metadata for the VM.os_type(string, optional): Operating system identifier (e.g.rhel_8x64,other_linux).disk_size_gb(int, optional): Size in GB for initial primary disk.storage_domain(string, optional): Target storage domain for disk.network_profile(string, optional): Name or UUID of vNIC profile (e.g.ovirtmgmt).wait(bool, optional, default: false): Whentrue, blocks until VM reaches unlockeddownstatus.timeout_seconds(int, optional, default: 120): Maximum wait duration.
Outputs (
VmCreateResult):success: Boolean indicating if VM was created.vm_id: UUID of the newly provisioned VM.vm_name: Name of the VM.cluster_name: Target cluster name.template_name: Base template name.status: Power/provisioning status (e.g."down"or"image_locked").memory_mb: Allocated RAM.cpu_cores: Total vCPUs.message: Summary of created virtual machine.
Example Output:
{
"success": true,
"vm_id": "5365d7a8-ff64-4dc7-b2c9-d97633b55565",
"vm_name": "testvm001",
"cluster_name": "DefaultCluster",
"template_name": "Blank",
"status": "down",
"memory_mb": 1024,
"cpu_cores": 1,
"message": "Virtual machine 'testvm001' created successfully in cluster 'DefaultCluster' from template 'Blank'."
}10. ovirt_vm_delete
Permanently deletes a virtual machine from the oVirt / OLVM engine. Safe-Mode protected: In Safe Mode (MCP_SAFE_MODE=true), requires explicit confirm=True. Prevents accidental deletion of running VMs unless force=True is explicitly specified.
Inputs:
name_or_id(string, required): VM display name or UUID.detach_only(bool, optional, default: false): Whentrue, virtual disks are preserved in storage domains and only detached from the VM. Whenfalse, disks are permanently erased.force(bool, optional, default: false): Whentrue, force-powers off a running VM before deletion and ignores disk locks.confirm(bool, optional, default: false): Explicit confirmation required whenMCP_SAFE_MODE=true.wait(bool, optional, default: false): Whentrue, blocks until the VM is confirmed removed from hypervisor inventory.timeout_seconds(int, optional, default: 60): Maximum wait duration.
Outputs (
VmDeleteResult):success: Boolean indicating if deletion was successful.vm_id: UUID of deleted virtual machine.vm_name: Name of deleted virtual machine.disks_detached_only: Whether disks were preserved.message: Outcome description.
Example Output:
{
"success": true,
"vm_id": "5365d7a8-ff64-4dc7-b2c9-d97633b55565",
"vm_name": "testvm001",
"disks_detached_only": false,
"message": "Virtual machine 'testvm001' deleted successfully. Attached disks were deleted."
}11. ovirt_vm_migrate
Live-migrates an actively running virtual machine to another hypervisor host with zero downtime.
Inputs:
name_or_id(string, required): VM display name or UUID.target_host(string, optional): Destination hypervisor host name or UUID. If omitted, the engine automatically selects the optimal host based on cluster load-balancing policies.force(bool, optional, default: false): Force migration even if the VM is marked as non-migratable.wait(bool, optional, default: false): Whentrue, blocks until migration completes and the VM is confirmed running on the destination host.timeout_seconds(int, optional, default: 120): Maximum wait duration.
Outputs (
VmMigrateResult):success: Boolean indicating if migration succeeded.vm_id: VM UUID.vm_name: VM display name.source_host: Source host before migration.target_host: Target host after migration.status: VM status after action ("up"or"migrating").message: Outcome description.
12. ovirt_vm_pin
Pins a virtual machine to run exclusively on a specific hypervisor host. Disables automatic cluster live migration and locks placement to the designated host.
Inputs:
name_or_id(string, required): VM display name or UUID.host(string, required): Target physical host name or UUID.
Outputs (
VmPinResult):success: Boolean indicating success.vm_id: VM UUID.vm_name: VM display name.affinity:"pinned".pinned_hosts: List of pinned host names.message: Outcome description.
13. ovirt_vm_unpin
Unpins a previously pinned virtual machine, restoring normal dynamic live migration and cluster load-balancing across all hosts. Reversible counterpart to ovirt_vm_pin.
Inputs:
name_or_id(string, required): VM display name or UUID.
Outputs (
VmPinResult):success: Boolean indicating success.vm_id: VM UUID.vm_name: VM display name.affinity:"migratable".pinned_hosts: Empty list[].message: Outcome description.
14. ovirt_vm_snapshot_list
Lists all point-in-time snapshots of a virtual machine, including snapshot UUID, description, status (ok, locked, in_preview), snapshot type (regular, active), creation timestamp, and RAM persist state.
Inputs:
name_or_id(string, required): VM display name or UUID.
Outputs:
list[VmSnapshotInfo]id: UUID of the snapshot.description: Snapshot description or label.snapshot_status: Snapshot state (ok,locked, etc.).snapshot_type:regular(restore point) oractive(live state container).date: ISO timestamp of creation.persist_memorystate: Whether RAM state was captured.
Example Output:
[
{
"id": "e42cfb8a-8c31-4191-8846-fcad77b5dcb0",
"description": "Pre-upgrade backup",
"snapshot_status": "ok",
"snapshot_type": "regular",
"date": "2026-11-18 14:30:00+00:00",
"persist_memorystate": false
}
]15. ovirt_vm_snapshot_create
Creates a point-in-time snapshot of a virtual machine. Supports live snapshots on running VMs as well as offline snapshots on stopped VMs.
Inputs:
name_or_id(string, required): VM display name or UUID.description(string, required): Informative description or label for the snapshot.persist_memory(bool, optional, default: false): Whentrue, saves running guest RAM state along with disk state.wait(bool, optional, default: false): Whentrue, blocks synchronously until snapshot creation completes and reachesokstatus.timeout_seconds(int, optional, default: 180): Maximum wait duration.
Outputs (
VmSnapshotResult):success: Boolean indicating if snapshot creation was initiated.action:"create".vm_id: VM UUID.vm_name: VM display name.snapshot_id: UUID of the created snapshot.message: Outcome description.
16. ovirt_vm_snapshot_restore
Restores (reverts) a virtual machine to a previous snapshot state. Destructive action: Requires explicit confirm=True in Safe Mode (MCP_SAFE_MODE=true). The virtual machine must be stopped (down) before restoring.
Dual Restore Paradigms:
Disk-only restore (
restore_memory=False): Restores disks to the crash-consistent snapshot point. The VM remains indownstatus until explicitly powered on.RAM + Disk restore (
restore_memory=True): Restores both disk state and running guest memory (RAM). Requires that the snapshot was created withpersist_memory=True. A strict pre-flight guard checks that the snapshot contains memory state before executing.
Inputs:
name_or_id(string, required): VM display name or UUID.snapshot_id(string, required): UUID of the snapshot to restore.restore_memory(bool, optional, default: false): Iftrue, restores the saved guest RAM memory state (requires snapshot created withpersist_memory=True).confirm(bool, optional, default: false): Confirmation required in Safe Mode.wait(bool, optional, default: false): Whentrue, blocks until restore finishes.timeout_seconds(int, optional, default: 180): Maximum wait duration.
Outputs (
VmSnapshotResult):success: Boolean indicating if restore succeeded.action:"restore".vm_id: VM UUID.vm_name: VM display name.snapshot_id: Restored snapshot UUID.restore_memory: Whether RAM state was restored.message: Outcome description.
17. ovirt_vm_snapshot_preview
Switches the virtual machine into preview mode on top of a historical snapshot without permanently overwriting the current state.
In oVirt/OLVM, previewing mounts temporary copy-on-write overlays on top of the snapshot disks. You can power on the VM, inspect services, and run validation scripts. If the results are unsatisfactory, use ovirt_vm_snapshot_undo to cleanly discard the preview without residue. If the results are confirmed, use ovirt_vm_snapshot_commit to make the snapshot permanently active.
Inputs:
name_or_id(string, required): VM display name or UUID.snapshot_id(string, required): UUID of the snapshot to preview.restore_memory(bool, optional, default: false): Iftrue, boots the VM directly from the saved RAM state.confirm(bool, optional, default: false): Confirmation required in Safe Mode.wait(bool, optional, default: false): Whentrue, blocks until snapshot status reachesin_preview.timeout_seconds(int, optional, default: 180): Maximum wait duration.
Outputs (
VmSnapshotResult):success: Boolean indicating preview initiated.action:"preview".vm_id: VM UUID.vm_name: VM display name.snapshot_id: UUID of previewed snapshot.restore_memory: Whether RAM state was restored.message: Outcome description.
18. ovirt_vm_snapshot_commit
Permanently commits an active snapshot preview, making the previewed state the VM's permanent operational baseline.
Inputs:
name_or_id(string, required): VM display name or UUID.confirm(bool, optional, default: false): Confirmation required in Safe Mode.wait(bool, optional, default: false): Whentrue, blocks until preview delta consolidation completes.timeout_seconds(int, optional, default: 180): Maximum wait duration.
Outputs (
VmSnapshotResult):success: Boolean indicating commit success.action:"commit".vm_id: VM UUID.vm_name: VM display name.message: Outcome description.
19. ovirt_vm_snapshot_undo
Undoes the active snapshot preview and restores the VM to its exact state before preview was initiated. Reversible counterpart to ovirt_vm_snapshot_preview. Discards all preview temporary disks without affecting historical snapshot data.
Inputs:
name_or_id(string, required): VM display name or UUID.confirm(bool, optional, default: false): Confirmation required in Safe Mode.wait(bool, optional, default: false): Whentrue, blocks until preview teardown completes and VM unlocks.timeout_seconds(int, optional, default: 180): Maximum wait duration.
Outputs (
VmSnapshotResult):success: Boolean indicating undo success.action:"undo".vm_id: VM UUID.vm_name: VM display name.message: Outcome description.
20. ovirt_vm_snapshot_delete
Deletes a snapshot and consolidates its delta disk changes back into the parent disk image. Destructive action: Requires explicit confirm=True in Safe Mode (MCP_SAFE_MODE=true). Reversible counterpart ensuring no unneeded snapshots linger in storage domains.
Inputs:
name_or_id(string, required): VM display name or UUID.snapshot_id(string, required): UUID of the snapshot to delete.confirm(bool, optional, default: false): Confirmation required in Safe Mode.wait(bool, optional, default: false): Whentrue, blocks until snapshot removal and consolidation complete.timeout_seconds(int, optional, default: 180): Maximum wait duration.
Outputs (
VmSnapshotResult):success: Boolean indicating success.action:"delete".vm_id: VM UUID.vm_name: VM display name.snapshot_id: Deleted snapshot UUID.message: Outcome description.
21. ovirt_vm_cdrom_list
Lists virtual CD-ROM drives configured on a virtual machine, reporting device UUIDs, attached ISO image file names, and whether each drive is empty.
Inputs:
name_or_id(string, required): VM display name or UUID.
Outputs:
list[VmCdromInfo]id: UUID of the CD-ROM device.file_id: Name of the attached ISO file, ornullif empty.is_empty: Boolean indicating whether media is inserted.
Example Output:
[
{
"id": "00000000-0000-0000-0000-000000000000",
"file_id": null,
"is_empty": true
}
]22. ovirt_vm_iso_attach
Attaches (mounts) an ISO file from an ISO storage domain into the virtual machine's CD-ROM drive. When the VM is running and current is omitted, media is automatically hot-plugged into the active guest and saved to persistent VM configuration.
Inputs:
name_or_id(string, required): VM display name or UUID.iso_file(string, required): ISO filename (must exist in an active ISO storage domain).cdrom_id(string, optional): Specific CD-ROM device UUID (defaults to primary drive).current(bool, optional): Iftrue, applies only to running guest (hot-swap); iffalse, applies only persistently; if omitted, automatically applies to both when running.
Outputs (
VmCdromResult):success: Boolean indicating success.action:"attach".vm_id: VM UUID.vm_name: VM display name.cdrom_id: Device UUID.iso_file: Attached ISO filename.current: Whether live guest media was hot-plugged.message: Outcome description.
23. ovirt_vm_iso_eject
Ejects / unmounts any mounted ISO media from the virtual machine's CD-ROM drive. Reversible counterpart to ovirt_vm_iso_attach. Supports live hot-eject on running VMs.
Inputs:
name_or_id(string, required): VM display name or UUID.cdrom_id(string, optional): Specific CD-ROM device UUID (defaults to primary drive).current(bool, optional): Iftrue, applies only to running guest; iffalse, applies persistently; if omitted, applies to both when running.
Outputs (
VmCdromResult):success: Boolean indicating success.action:"eject".vm_id: VM UUID.vm_name: VM display name.cdrom_id: Device UUID.iso_file:null.current: Whether live eject was performed.message: Outcome description.
24. ovirt_storage_iso_list
Lists all available ISO image installation files stored across active ISO storage domains. Enables AI agents and administrators to discover available OS installation media before attaching.
Inputs:
storage_domain(string, optional): Filter by specific storage domain name or UUID.
Outputs:
list[IsoFileInfo]id: File ID or filename.name: ISO filename.storage_domain_id: ISO storage domain UUID.storage_domain_name: ISO storage domain display name.
Example Output:
[
{
"id": "OracleLinux-R8-U10-x86_64-dvd.iso",
"name": "OracleLinux-R8-U10-x86_64-dvd.iso",
"storage_domain_id": "de66dbc8-c5df-48ee-993e-387a9283f7e3",
"storage_domain_name": "ISO"
}
]25. ovirt_vm_disk_list
Lists all virtual disks attached to a virtual machine, reporting attachment UUID, underlying disk UUID, alias/name, interface (virtio, virtio_scsi), bootable flag, active status, read-only flag, provisioned size in GB, actual storage used in GB, disk format (cow or raw), and storage domain.
Inputs:
name_or_id(string, required): VM display name or UUID.
Outputs:
list[VmDiskAttachmentInfo]
26. ovirt_vm_disk_attach
Attaches an existing floating virtual disk to a virtual machine. Configurable interface (virtio, virtio_scsi, sata, ide), bootable flag, active state, and read-only mode.
Inputs:
name_or_id(string, required): VM display name or UUID.disk_id(string, required): UUID of the existing floating disk.interface(string, optional, default: "virtio"): Controller bus interface.bootable(bool, optional, default: false): Whether disk is boot device.active(bool, optional, default: true): Whether disk is active/plugged.read_only(bool, optional, default: false): Whether to mount read-only.
Outputs (
VmDiskAttachmentResult):success: Boolean indicating success.action:"attach".vm_id: VM UUID.vm_name: VM display name.disk_id: Attached disk UUID.interface: Interface type used.message: Outcome description.
27. ovirt_vm_disk_detach
Detaches a virtual disk from a virtual machine without deleting the underlying storage image (detach_only=True). Reversible counterpart to ovirt_vm_disk_attach. Destructive action: Requires explicit confirm=True in Safe Mode (MCP_SAFE_MODE=true).
Inputs:
name_or_id(string, required): VM display name or UUID.disk_id(string, required): UUID of the disk to detach.confirm(bool, optional, default: false): Safe-mode confirmation flag.wait(bool, optional, default: false): Blocks until confirmed detached.timeout_seconds(int, optional, default: 60): Maximum wait duration.
Outputs (
VmDiskAttachmentResult):success: Boolean indicating success.action:"detach".vm_id: VM UUID.vm_name: VM display name.disk_id: Detached disk UUID.message: Outcome description.
28. ovirt_vm_disk_create
Creates a brand-new virtual disk and attaches it directly to a virtual machine. Supports thin-provisioned COW or RAW formats, target storage domains, interface selection, and synchronous wait until disk images are fully allocated.
Inputs:
name_or_id(string, required): VM display name or UUID.size_gb(int, required): Provisioned disk capacity in gigabytes.storage_domain(string, required): Target storage domain name or UUID.disk_name(string, optional): Custom alias for disk.disk_format(string, optional, default: "cow"): Format ("cow"or"raw").interface(string, optional, default: "virtio"): Interface type ("virtio"or"virtio_scsi").bootable(bool, optional, default: false): Mark as bootable.active(bool, optional, default: true): Activate immediately.wait(bool, optional, default: false): Block until disk is unlocked and ready.timeout_seconds(int, optional, default: 120): Maximum wait duration.
Outputs (
VmDiskAttachmentResult):success: Boolean indicating success.action:"create".disk_id: Newly created disk UUID.message: Outcome description.
29. ovirt_disk_resize
Expands the provisioned capacity of a virtual disk to a larger size in gigabytes. Safe-Mode protected: requires confirm=True. Note: In virtualization hypervisors, disk shrinking is strictly prohibited to protect against filesystem truncation and data loss.
Inputs:
disk_id(string, required): UUID of the virtual disk to resize.size_gb(int, required): New total provisioned capacity in GB (must be strictly larger than current size).confirm(bool, optional, default: false): Safe-mode confirmation flag.
Outputs (
DiskResizeResult):success: Boolean indicating success.disk_id: Resized disk UUID.old_size_gb: Size prior to expansion.new_size_gb: Expanded size in GB.message: Outcome description.
30. ovirt_disk_list
Lists all virtual disks in the virtualization environment across storage domains, including floating unattached disks and attached disks.
Inputs:
storage_domain(string, optional): Filter by specific storage domain name or UUID.search(string, optional): Engine search query filter.
Outputs:
list[DiskDetail]id: Disk UUID.name: Disk name or alias.status: State (ok,locked, etc.).provisioned_size_gb: Allocated logical capacity.actual_size_gb: Storage space physically consumed.disk_format:"cow"or"raw".content_type:"data","iso", or"ovf_store".storage_domain_name: Hosting storage domain.
31. ovirt_vm_nic_list
Lists all virtual network interface cards (vNICs) attached to a virtual machine, reporting interface name, device UUID, assigned MAC address, interface model (virtio, e1000), plugged state, linked state, and associated vNIC profile.
Inputs:
name_or_id(string, required): VM display name or UUID.
Outputs:
list[VmNicDetail]
32. ovirt_vm_nic_add
Adds a new virtual network interface card (vNIC) to a virtual machine, attaching it to a specific vNIC profile on a logical network.
Inputs:
name_or_id(string, required): VM display name or UUID.name(string, required): Name for new vNIC (e.g.'nic2').profile(string, required): Name or UUID of vNIC profile (e.g.'ovirtmgmt').interface(string, optional, default: "virtio"): Controller model ("virtio","e1000").plugged(bool, optional, default: true): Whether NIC is plugged into slot.linked(bool, optional, default: true): Whether network cable is linked.
Outputs (
VmNicResult):success: Boolean indicating success.action:"add".vm_id: VM UUID.vm_name: VM display name.nic_id: Device UUID.nic_name: Interface name.mac_address: Generated MAC address.message: Outcome description.
33. ovirt_vm_nic_remove
Removes a virtual network interface card (vNIC) from a virtual machine. Reversible counterpart to ovirt_vm_nic_add. Destructive action: Requires explicit confirm=True in Safe Mode (MCP_SAFE_MODE=true).
Inputs:
name_or_id(string, required): VM display name or UUID.nic_name_or_id(string, required): Name or UUID of vNIC to remove.confirm(bool, optional, default: false): Safe-mode confirmation flag.
Outputs (
VmNicResult):success: Boolean indicating success.action:"remove".vm_id: VM UUID.nic_id: Removed vNIC UUID.nic_name: Removed vNIC name.message: Outcome description.
34. ovirt_network_profile_list
Lists available virtual network interface profiles (vNIC profiles) across logical networks in the environment.
Inputs:
network(string, optional): Filter by specific logical network name or UUID.
Outputs:
list[VnicProfileInfo]id: Profile UUID.name: Profile name.network_name: Parent logical network name.network_id: Parent logical network UUID.pass_through: Whether SR-IOV passthrough is enabled.port_mirroring: Whether port mirroring is active.
35. ovirt_vm_update
Updates virtual machine compute resources (RAM memory in MB, CPU cores/sockets/threads), description, or High Availability failover status. Modifying hardware CPU or memory is Safe-Mode guarded and requires explicit confirm=True.
Inputs:
name_or_id(string, required): VM display name or UUID.memory_mb(int, optional): New RAM allocation in megabytes.cpu_cores(int, optional): CPU cores per socket.cpu_sockets(int, optional): CPU sockets count.cpu_threads(int, optional): Threads per CPU core.description(string, optional): Updated description text.ha_enabled(bool, optional): Enable or disable High Availability.confirm(bool, optional, default: false): Safe-mode confirmation flag.
Outputs (
VmUpdateResult):success: Boolean indicating success.vm_id: VM UUID.vm_name: VM display name.memory_mb: Confirmed RAM size in MB.cpu_cores: Confirmed vCPU cores.ha_enabled: Confirmed HA flag.message: Outcome description.
36. ovirt_vm_graphics_consoles
Lists available graphical display consoles (VNC / SPICE) configured for a virtual machine, reporting protocol, display ports, and console device identifiers.
Inputs:
name_or_id(string, required): VM display name or UUID.
Outputs:
list[VmGraphicsConsoleInfo]id: Console device UUID.protocol:"vnc"or"spice".port: Cleartext display port.tls_port: Encrypted TLS display port.
37. ovirt_vm_ticket
Generates a temporary, single-use authentication password/ticket to connect to a running virtual machine's graphical console (VNC / SPICE). The virtual machine must be running (status='up').
Inputs:
name_or_id(string, required): VM display name or UUID.expiry_seconds(int, optional, default: 120): Validity window in seconds.
Outputs (
VmConsoleTicket):vm_id: VM UUID.vm_name: VM display name.ticket_value: Temporary connection password.expiry_seconds: Ticket validity duration.message: Instructions for connecting.
38. ovirt_host_list
Lists all hypervisor hosts in the virtualization environment across clusters. Reports operational status, cluster name, management IP address, physical CPU topology, total RAM in GB, active VMs count, SPM (Storage Pool Manager) status, and nested virtualization detection.
Inputs:
cluster(string, optional): Filter hosts by cluster name or UUID.status(string, optional): Filter by status (e.g.'up','maintenance','down').
Outputs:
list[HostSummary]id: Hypervisor host UUID.name: FQDN / display name.status: Host state (up,maintenance,down,non_operational).cluster_name: Parent cluster name.address: Management network IP address / hostname.active_vms_count: Number of virtual machines currently running on this host.spm_status: Storage Pool Manager role (spm,contending,none).is_nested: Boolean indicating whether hypervisor is nested inside VMware, KVM, etc.cpu_model: Host CPU model detected by engine.cpu_cores: Physical core count.cpu_sockets: Physical socket count.total_memory_gb: Total physical RAM in gigabytes.update_available: Boolean indicating whether OS or package updates are available for the host.
Example Output:
[
{
"id": "bd72f2ef-9472-4b94-b961-08cfd40dbc31",
"name": "olvmhost002.example.com",
"status": "up",
"cluster_name": "DefaultCluster",
"cluster_id": "b873d6c8-d13e-42f6-980a-fe8d4a01fdc3",
"address": "192.0.2.12",
"active_vms_count": 0,
"spm_status": "none",
"is_nested": true,
"cpu_model": "AMD Ryzen 5 3600 6-Core Processor",
"cpu_cores": 1,
"cpu_sockets": 10,
"total_memory_gb": 20.71,
"update_available": true
}
]39. ovirt_host_get
Retrieves comprehensive hardware, BIOS, OS distribution, kernel, VDSM/libvirt versions, power management (fencing) configuration, and hardware device counts for a single hypervisor host.
Inputs:
name_or_id(string, required): Host display name or UUID.
Outputs (
HostDetail):id: Host UUID.name: Host display name.status: Operational status.cluster_name: Cluster name.address: IP address.ssh_port: SSH daemon port.hardware: Manufacturer, product model, chassis serial number, UUID.os: OS distribution, release, kernel version, KVM, libvirt, and VDSM node versions.power_management: Out-of-band IPMI / fencing configuration (enabled,pm_type,address).nics_count: Physical network interface count.numa_nodes_count: NUMA topology node count.update_available: Boolean indicating whether OS or package updates are available.
40. ovirt_host_stats
Retrieves real-time telemetry metrics and system load statistics for a hypervisor host, including active CPU utilization percentage, user/system/idle breakdown, 5-minute system load average, memory allocated/used/free/percentage, swap usage, active VM count, and system boot time.
Inputs:
name_or_id(string, required): Host display name or UUID.
Outputs (
HostStats):host_id: Host UUID.host_name: Host display name.cpu_usage_percent: Total CPU active utilization (0-100%).cpu_user_percent: User space CPU consumption %.cpu_system_percent: Kernel space CPU consumption %.cpu_idle_percent: CPU idle %.cpu_load_avg_5m: 5-minute system load average.memory_total_gb: Total RAM in GB.memory_used_gb: Consumed RAM in GB.memory_free_gb: Available RAM in GB.memory_used_percent: Memory utilization %.swap_used_mb: Active swap memory in MB.boot_time: Formatted system boot timestamp.
41. ovirt_host_maintenance
Places a hypervisor host into maintenance mode (deactivate). Initiates an orderly, non-disruptive evacuation of all running virtual machines, live-migrating them to other active hosts in the cluster.
Enterprise Pre-condition & Safety Guards:
Pinned VM Guard: If any virtual machine is pinned exclusively to this host (
affinity="pinned"or non-migratable), oVirt cannot live-migrate it.ovirt_host_maintenanceinspects running workloads and automatically rejects the operation with a list of affected pinned VMs unlessstop_pinned_vms=Trueis explicitly specified.SPM Role Awareness: If the host is currently the Storage Pool Manager (
spm_status="spm"), the tool logs a notice that SPM role re-election and data center storage lease migration will occur.Non-binary State Polling: Live migration of workloads across multi-gigabyte VM memory spaces takes time. When
wait=Trueis set, the tool blocks synchronously, tracking the transitionalpreparing_for_maintenancestate until host status is confirmedmaintenanceAND active VM count reaches 0.
Inputs:
name_or_id(string, required): Host display name or UUID.stop_pinned_vms(bool, optional, default: false): Allow engine to stop/shut down non-migratable pinned VMs.confirm(bool, optional, default: false): Safe-mode confirmation flag.wait(bool, optional, default: false): Block until maintenance mode is achieved and VMs count is 0.timeout_seconds(int, optional, default: 300): Maximum wait duration.
Outputs (
HostLifecycleResult):success: Boolean indicating success.action:"maintenance".host_id: Host UUID.host_name: Host display name.previous_status: Status prior to command.current_status:"maintenance".active_vms_count: Confirmed remaining VMs (0 upon completion).message: Outcome description.
42. ovirt_host_activate
Activates a hypervisor host from maintenance mode back to active up status. Reversible counterpart to ovirt_host_maintenance, restoring the hypervisor's ability to host workloads and participate in cluster load-balancing.
Inputs:
name_or_id(string, required): Host display name or UUID.wait(bool, optional, default: false): Block until host reaches activeupstatus.timeout_seconds(int, optional, default: 180): Maximum wait duration.
Outputs (
HostLifecycleResult):success: Boolean indicating success.action:"activate".host_id: Host UUID.host_name: Host display name.previous_status: Status prior to activation.current_status:"up".message: Outcome description.
43. ovirt_host_restart
Reboots a hypervisor host via out-of-band power management fencing.
Strict Enterprise Safety Gate ("Guard-Before-Act"): To prevent hypervisor crashes and catastrophic service outages:
Maintenance Status Gate: The host MUST be in
maintenancestatus. If the host is currently active (up),preparing_for_maintenance, or in any other transitional state, reboot is strictly rejected.Zero VMs Gate: Running virtual machine count MUST be exactly 0.
Power Management / Fencing Gate: Verifies that physical IPMI / fencing agents are configured and enabled. In nested virtualization (e.g. VMware ESXi / KVM nested nodes) or lab setups without physical IPMI, the tool detects this upfront and reports an explicit diagnostic error rather than triggering an unrecoverable failure.
Inputs:
name_or_id(string, required): Host display name or UUID.confirm(bool, optional, default: false): Confirmation required whenMCP_SAFE_MODE=true.wait(bool, optional, default: false): Block until host completes reboot cycle.timeout_seconds(int, optional, default: 300): Maximum wait duration.
Outputs (
HostLifecycleResult):success: Boolean indicating reboot initiated.action:"restart".host_id: Host UUID.host_name: Host display name.previous_status: Previous status ("maintenance").current_status: New status ("reboot"or"maintenance").message: Outcome description.
44. ovirt_host_nic_list
Lists physical network interfaces (pNICs) on a hypervisor host, including device name, MAC address, link speed in Mbps, link status (up/down), configured IPv4/IPv6 addresses, attached logical networks, and bonding slave memberships.
Inputs:
name_or_id(string, required): Host display name or UUID.
Outputs:
list[HostNicInfo]
45. ovirt_host_numa_list
Lists Non-Uniform Memory Access (NUMA) node topology for a hypervisor host, reporting node index, RAM memory allocated to each NUMA node in MB, and assigned physical CPU core IDs.
Inputs:
name_or_id(string, required): Host display name or UUID.
Outputs:
list[HostNumaNodeInfo]
46. ovirt_host_device_list
Lists hardware and PCI bus devices configured on a hypervisor host (SR-IOV virtual functions, GPU passthrough devices, Fibre Channel HBAs, network adapters).
Inputs:
name_or_id(string, required): Host display name or UUID.max_devices(int, optional, default: 50): Maximum devices to return.
Outputs:
list[HostDeviceInfo]id: PCI device address identifier.name: Device name.product: Hardware product description.vendor: Hardware vendor name.driver: Active kernel driver module.iommu_group: IOMMU group index for PCI passthrough.
47. ovirt_host_storage_list
Lists storage domains and SAN/block storage server connections accessible to a hypervisor host.
Inputs:
name_or_id(string, required): Host display name or UUID.
Outputs:
list[dict]containing storage domain ID, name, storage type, and target addresses.
48. ovirt_host_events
Retrieves host-specific audit history, hardware alerts, SPM role elections, and operational events.
Inputs:
name_or_id(string, required): Host display name or UUID.max_events(int, optional, default: 25): Maximum number of events to return.severity(string, optional): Filter by severity ('normal','warning','error','alert').
Outputs:
list[HostEvent]id: Event ID.code: oVirt event code integer.severity: Event severity level.description: Event message.timestamp: Event timestamp.
49. ovirt_affinity_label_list
Lists all global Affinity Labels registered in the oVirt/OLVM engine, including the hypervisor hosts and virtual machines assigned to each label.
Inputs: None.
Outputs:
list[AffinityLabelInfo]id: UUID of the label.name: Human-readable label name.hosts: List of hypervisor host names currently bearing this label.vms: List of virtual machine names currently bearing this label.
50. ovirt_affinity_label_create
Creates a new global Affinity Label in oVirt/OLVM.
Inputs:
name(string, required): Unique label name (e.g.database-nodes,pci-passthrough-hosts).
Outputs:
AffinityLabelResultsuccess: Whether creation succeeded.label_id: UUID of the created label.label_name: Name of the label.message: Outcome description.
51. ovirt_affinity_label_delete
Deletes an Affinity Label. Protected by safe-mode confirmation (confirm=True). If the label is currently attached to hosts or VMs, oVirt requires detaching it first. Setting detach_first=True safely unassigns the label from all entities before deletion.
Inputs:
name_or_id(string, required): Label name or UUID.confirm(bool, optional, default: False): Confirmation flag required in safe-mode.detach_first(bool, optional, default: False): Automatically unassign from all hosts and VMs before deleting to avoid HTTP 409 conflicts.
Outputs:
AffinityLabelResult
52. ovirt_host_label_list
Lists all Affinity Labels assigned to a specific hypervisor host.
Inputs:
host_name_or_id(string, required): Host name or UUID.
Outputs:
list[str]of affinity label names.
53. ovirt_host_label_assign
Assigns an Affinity Label to a hypervisor host.
Inputs:
host_name_or_id(string, required): Host name or UUID.label_name_or_id(string, required): Affinity label name or UUID.
Outputs:
EntityLabelResultsuccess: Whether assignment succeeded.entity_name: Name of the host.label_name: Name of the assigned label.current_labels: Complete list of labels currently on this host.
54. ovirt_host_label_unassign
Unassigns an Affinity Label from a hypervisor host (symmetric, reversible counterpart of ovirt_host_label_assign).
Inputs:
host_name_or_id(string, required): Host name or UUID.label_name_or_id(string, required): Affinity label name or UUID to remove.
Outputs:
EntityLabelResult
55. ovirt_vm_label_list
Lists all Affinity Labels assigned to a virtual machine.
Inputs:
vm_name_or_id(string, required): VM name or UUID.
Outputs:
list[str]of affinity label names.
56. ovirt_vm_label_assign
Assigns an Affinity Label to a virtual machine.
Inputs:
vm_name_or_id(string, required): VM name or UUID.label_name_or_id(string, required): Affinity label name or UUID.
Outputs:
EntityLabelResult
57. ovirt_vm_label_unassign
Unassigns an Affinity Label from a virtual machine (symmetric, reversible counterpart of ovirt_vm_label_assign).
Inputs:
vm_name_or_id(string, required): VM name or UUID.label_name_or_id(string, required): Affinity label name or UUID to remove.
Outputs:
EntityLabelResult
58. ovirt_cluster_affinity_group_list
Lists all Affinity Groups defined within a cluster, including rules (positive/negative, enforcing), member VMs, member Hosts, and label associations.
Inputs:
cluster_name_or_id(string, required): Cluster name or UUID.
Outputs:
list[AffinityGroupInfo]id: UUID of the affinity group.name: Group name.cluster_name: Name of the cluster.vms_rule:AffinityRuleConfig(enabled,positive,enforcing).hosts_rule:AffinityRuleConfig(enabled,positive,enforcing).vms: Member VM names or IDs.hosts: Member Host names or IDs.vm_labels: Member VM label names.host_labels: Member Host label names.
59. ovirt_cluster_affinity_group_get
Retrieves detailed configuration and member lists of a specific Affinity Group in a cluster.
Inputs:
cluster_name_or_id(string, required): Cluster name or UUID.group_name_or_id(string, required): Affinity group name or UUID.
Outputs:
AffinityGroupInfo
60. ovirt_cluster_affinity_group_create
Creates a new Affinity Group in a cluster with fine-grained VM-to-VM and VM-to-Host rules.
Inputs:
cluster_name_or_id(string, required): Cluster name or UUID.name(string, required): Unique name for the group.description(string, optional): Purpose description.priority(float, optional): Scheduling priority (e.g.1.0-5.0).vm_positive(bool, optional, default: True): Positive VM affinity (True, run together) or anti-affinity (False, run on separate hypervisors).vm_enforcing(bool, optional, default: False): Mandatory hard rule (True) vs. soft preference (False).vm_enabled(bool, optional, default: True): Enable/disable the VM rule.host_positive(bool, optional, default: True): Positive Host affinity (True, run on specified hosts) or negative (False, forbidden on specified hosts).host_enforcing(bool, optional, default: False): Mandatory host enforcement (True) vs soft preference (False).host_enabled(bool, optional, default: True): Enable/disable the Host rule.vms(list[str], optional): List of member VM names or UUIDs.hosts(list[str], optional): List of member Host names or UUIDs.vm_labels(list[str], optional): List of member VM Affinity Label names or UUIDs.host_labels(list[str], optional): List of member Host Affinity Label names or UUIDs.
Outputs:
AffinityGroupResult
61. ovirt_cluster_affinity_group_update
Updates rules, settings, or member lists of an existing Affinity Group.
Inputs:
cluster_name_or_id(string, required): Cluster name or UUID.group_name_or_id(string, required): Affinity group name or UUID.name(string, optional): Rename group.description(string, optional): Update description.priority(float, optional): Update priority.vm_positive(bool, optional): Update VM positive/anti-affinity rule.vm_enforcing(bool, optional): Update VM enforcement.host_positive(bool, optional): Update Host affinity rule.host_enforcing(bool, optional): Update Host enforcement.vms(list[str], optional): Replace complete list of member VMs.hosts(list[str], optional): Replace complete list of member Hosts.vm_labels(list[str], optional): Replace complete list of member VM labels.host_labels(list[str], optional): Replace complete list of member Host labels.
Outputs:
AffinityGroupResult
62. ovirt_cluster_affinity_group_delete
Deletes an Affinity Group from a cluster. Protected by safe-mode confirmation (confirm=True).
Inputs:
cluster_name_or_id(string, required): Cluster name or UUID.group_name_or_id(string, required): Affinity group name or UUID.confirm(bool, optional, default: False): Confirmation flag required in safe-mode.
Outputs:
AffinityGroupResult
63. ovirt_host_network_attachment_list
Lists all logical network attachments on a hypervisor host, resolving which oVirt network (e.g. ovirtmgmt) is attached to which physical NIC or bond (e.g. eth0), along with IPv4 assignment method, address, netmask, gateway, and in-sync status.
Inputs:
host_name_or_id(string, required): Host name or UUID.
Outputs:
list[HostNetworkAttachmentInfo]id: UUID of the attachment.network_name: Logical network name.host_nic_name: Physical NIC or bond name.boot_protocol:static,dhcp, ornone.ip_address: Assigned IPv4 address.in_sync: Boolean indicating whether host network settings match engine definitions.
64. ovirt_host_iscsi_discover
Discovers available iSCSI targets on a storage portal from the designated hypervisor host via OS kernel discovery.
Inputs:
host_name_or_id(string, required): Host name or UUID.address(string, required): IP address or hostname of the iSCSI portal (e.g.192.0.2.10).port(int, optional, default: 3260): iSCSI portal port.username(string, optional): CHAP username.password(string, optional): CHAP password.
Outputs:
HostIscsiDiscoverResulttargets: List of discovered target IQN strings.count: Total count of targets found.
65. ovirt_host_iscsi_login
Logs in to an iSCSI target portal from a hypervisor host, discovering LUN block devices (/dev/mapper/...).
Inputs:
host_name_or_id(string, required): Host name or UUID.address(string, required): iSCSI portal IP or hostname.target(string, required): Target IQN to log in to.port(int, optional, default: 3260): Portal port.username(string, optional): CHAP username.password(string, optional): CHAP password.
Outputs:
HostIscsiLoginResult
66. ovirt_host_network_sync
Synchronizes out-of-sync network attachments on a hypervisor host with engine definitions, featuring automatic connectivity rollback protection (check_connectivity=True).
Inputs:
host_name_or_id(string, required): Host name or UUID.network_attachment_id(string, optional): Specific attachment ID to synchronize. If omitted, synchronizes all out-of-sync attachments on the host.
Outputs:
HostNetworkSetupResult
67. ovirt_storage_domain_list
Lists all Storage Domains in oVirt / OLVM with capacity telemetry, storage protocols, format versions, and attached Data Centers.
Inputs: None.
Outputs:
list[StorageDomainSummary]id: UUID of the storage domain.name: Domain name.type: Domain role (data,iso,export,image).storage_type: Protocol (nfs,iscsi,fcp,glance,local).status:active,maintenance,unattached, orinactive.available_gb: Free space in GB.used_gb: Used space in GB.total_gb: Total space in GB.usage_percent: Utilization percentage.data_centers: List of attached Data Center names.
68. ovirt_storage_domain_get
Retrieves deep telemetry, thresholds, and stored object counts (disks, templates, VMs) for a Storage Domain.
Inputs:
name_or_id(string, required): Storage domain name or UUID.
Outputs:
StorageDomainDetaildisks_count: Number of virtual disks stored.templates_count: Number of VM templates stored.vms_count: Number of VMs stored.supports_discard: Boolean indicating TRIM / discard support.warning_low_space_indicator: Low space threshold percentage.critical_space_action_blocker: Critical blocking space threshold in GB.
69. ovirt_storage_domain_create_nfs
Creates a new NFS Storage Domain initialized via a designated hypervisor host.
Inputs:
name(string, required): Unique name for the storage domain.host_name_or_id(string, required): Hypervisor host responsible for initializing metadata.address(string, required): NFS server IP or hostname (e.g.192.0.2.20).path(string, required): NFS export path (e.g./exports/data).domain_type(string, optional, default: 'data'):data,iso, orexport.nfs_version(string, optional, default: 'auto'):auto,v3,v4,v4_1,v4_2.description(string, optional): Description.
Outputs:
StorageDomainResult
70. ovirt_storage_domain_attach
Attaches a Storage Domain to a Data Center.
Inputs:
storage_domain_name_or_id(string, required): Storage domain name or UUID.data_center_name_or_id(string, required): Target Data Center name or UUID.
Outputs:
StorageDomainResult
71. ovirt_storage_domain_activate
Activates an attached Storage Domain in a Data Center.
Inputs:
storage_domain_name_or_id(string, required): Storage domain name or UUID.data_center_name_or_id(string, required): Data Center name or UUID.
Outputs:
StorageDomainResult
72. ovirt_storage_domain_maintenance
Moves an attached Storage Domain to maintenance mode in a Data Center (deactivate), preparing it for safe detachment.
Inputs:
storage_domain_name_or_id(string, required): Storage domain name or UUID.data_center_name_or_id(string, required): Data Center name or UUID.
Outputs:
StorageDomainResult
73. ovirt_storage_domain_detach
Detaches a Storage Domain from a Data Center (symmetric, reversible counterpart of ovirt_storage_domain_attach). Domain must first be in maintenance mode.
Inputs:
storage_domain_name_or_id(string, required): Storage domain name or UUID.data_center_name_or_id(string, required): Data Center name or UUID.
Outputs:
StorageDomainResult
74. ovirt_storage_domain_delete
Deletes or unregisters a Storage Domain from oVirt / OLVM. Protected by safe-mode confirmation (confirm=True). If the domain is currently attached to an active Data Center, deletion is blocked by pre-flight guards to protect data integrity.
Inputs:
name_or_id(string, required): Storage domain name or UUID.host_name_or_id(string, optional): Hypervisor host executing the deletion/format.format(bool, optional, default: False): Whether to wipe/format storage metadata.confirm(bool, optional, default: False): Confirmation flag required in safe-mode.
Outputs:
StorageDomainResult
75. ovirt_disk_move
Moves a virtual disk to a different Storage Domain (Storage vMotion / offline disk migration). Safely migrates the underlying disk image between active storage domains.
Inputs:
disk_name_or_id(string, required): Name or UUID of the virtual disk to migrate.storage_domain_name_or_id(string, required): Target Storage Domain name or UUID.wait(bool, optional, default: True): Whether to synchronously block until migration completes.timeout(int, optional, default: 300): Maximum time in seconds to wait for migration.
Outputs:
DiskOperationResult
76. ovirt_disk_copy
Clones / copies a virtual disk to a target Storage Domain. Allows creating an independent copy with an optional new disk alias.
Inputs:
disk_name_or_id(string, required): Name or UUID of the virtual disk to clone.storage_domain_name_or_id(string, required): Target Storage Domain name or UUID.new_alias(string, optional): Optional new display name / alias for the copied disk.wait(bool, optional, default: True): Whether to synchronously block until copy completes.timeout(int, optional, default: 300): Maximum time in seconds to wait for copy.
Outputs:
DiskOperationResult
77. ovirt_disk_sparsify
Reclaims zeroed free space from a raw-formatted virtual disk (sparsification / hole punching). Compacts the disk image on the underlying storage domain.
Inputs:
disk_name_or_id(string, required): Name or UUID of the virtual disk to sparsify.wait(bool, optional, default: True): Whether to wait for sparsification to complete.timeout(int, optional, default: 300): Maximum wait time in seconds.
Outputs:
DiskOperationResult
78. ovirt_template_list
Lists all virtual machine templates and golden images in the virtualization environment, including the system Blank template, custom images, hardware specs (vCPU, RAM), and versioning.
Inputs:
search(string, optional): Filter query (e.g.name=gold*,status=ok).
Outputs:
list[TemplateSummary]
79. ovirt_template_get
Retrieves deep technical configuration and hardware profile of an oVirt / OLVM template, including attached disk references, NIC count, CPU topology, memory, and OS type.
Inputs:
name_or_id(string, required): Template name or UUID.
Outputs:
TemplateDetail
80. ovirt_template_create_from_vm
Creates a new reusable template / golden image from an existing virtual machine. The source virtual machine must be powered off (down) to snapshot disk images.
Inputs:
vm_name_or_id(string, required): Name or UUID of the source virtual machine.template_name(string, required): Name for the new template.description(string, optional): Optional descriptive text.wait(bool, optional, default: True): Whether to synchronously block until template provisioning finishes.timeout(int, optional, default: 300): Maximum wait time in seconds.
Outputs:
TemplateResult
81. ovirt_template_delete
Deletes an oVirt / OLVM template from the environment. Protected by safe-mode confirmation (confirm=True). The system Blank template is permanently protected from deletion by pre-flight guards.
Inputs:
name_or_id(string, required): Template name or UUID.confirm(bool, optional, default: False): Confirmation flag required in safe-mode.wait(bool, optional, default: True): Whether to synchronously block until removal completes.timeout(int, optional, default: 180): Maximum wait time in seconds.
Outputs:
TemplateResult
82. ovirt_datacenter_list
Lists all Data Centers in the virtualization environment, including status (up, uninitialized), storage type (shared, local), compatibility version, and quota mode.
Inputs:
search(string, optional): Filter query (e.g.status=up,name=Home*).
Outputs:
list[DataCenterSummary]
83. ovirt_datacenter_get
Retrieves complete technical specification of a Data Center, including attached clusters, attached Storage Domains, and defined logical networks.
Inputs:
name_or_id(string, required): Data Center name or UUID.
Outputs:
DataCenterDetail
84. ovirt_quota_list
Lists resource quotas defined across Data Centers or filtered by a specific Data Center.
Inputs:
data_center(string, optional): Data Center name or UUID filter.
Outputs:
list[QuotaSummary]
85. ovirt_quota_get
Retrieves detailed compute and storage limitations defined by a quota, including vCPU limits, memory limits, and storage domain space ceilings.
Inputs:
name_or_id(string, required): Quota name or UUID.data_center(string, optional): Data Center name or UUID scoping the search.
Outputs:
QuotaDetail
86. ovirt_quota_create
Creates a new resource quota under a designated Data Center.
Inputs:
name(string, required): Name for the new quota.data_center(string, required): Name or UUID of the parent Data Center.description(string, optional): Optional descriptive notes.
Outputs:
QuotaResult
87. ovirt_quota_delete
Deletes a resource quota from a Data Center. Protected by safe-mode confirmation (confirm=True). The system Default quota is protected by pre-flight guards.
Inputs:
name_or_id(string, required): Quota name or UUID.data_center(string, required): Name or UUID of the parent Data Center.confirm(bool, optional, default: False): Confirmation flag required in safe-mode.
Outputs:
QuotaResult
88. ovirt_network_list
Lists logical networks across Data Centers or filtered by Data Center, including 802.1Q VLAN encapsulation tag, MTU, and status.
Inputs:
data_center(string, optional): Data Center name or UUID filter.
Outputs:
list[LogicalNetworkSummary]
89. ovirt_network_create
Creates a new logical network in a Data Center with optional VLAN tagging and custom MTU (e.g. jumbo frames).
Inputs:
name(string, required): Name for the logical network.data_center(string, required): Name or UUID of the parent Data Center.vlan_id(int, optional): Optional 802.1Q VLAN encapsulation tag (1-4094).mtu(int, optional): Optional MTU payload size (e.g. 1500, 9000).description(string, optional): Optional descriptive notes.
Outputs:
LogicalNetworkResult
90. ovirt_network_delete
Deletes a logical network from a Data Center. Protected by safe-mode confirmation (confirm=True). The default management network ovirtmgmt is permanently protected from deletion.
Inputs:
name_or_id(string, required): Network name or UUID.data_center(string, optional): Data Center name or UUID scoping the search.confirm(bool, optional, default: False): Confirmation flag required in safe-mode.
Outputs:
LogicalNetworkResult
91. ovirt_tag_list
Lists hierarchical inventory tags in the oVirt / OLVM virtualization environment, including tag UUID, display name, description, and parent link.
Inputs:
search(string, optional): Optional search query.
Outputs:
list[TagSummary]
92. ovirt_tag_create
Creates a new inventory tag in oVirt / OLVM with optional parent hierarchical nesting.
Inputs:
name(string, required): Name for the new tag.description(string, optional): Optional descriptive text.parent(string, optional): Optional parent tag name or UUID for hierarchical nesting.
Outputs:
TagResult
93. ovirt_tag_delete
Deletes an inventory tag from oVirt / OLVM. Protected by safe-mode confirmation (confirm=True). The system root tag is protected from removal.
Inputs:
name_or_id(string, required): Tag name or UUID.confirm(bool, optional, default: False): Confirmation flag required in safe-mode.
Outputs:
TagResult
94. ovirt_vm_tag_assign
Assigns an inventory tag to a virtual machine.
Inputs:
vm_name_or_id(string, required): Virtual machine name or UUID.tag_name_or_id(string, required): Tag name or UUID.
Outputs:
TagAssignmentResult
95. ovirt_vm_tag_unassign
Unassigns an inventory tag from a virtual machine.
Inputs:
vm_name_or_id(string, required): Virtual machine name or UUID.tag_name_or_id(string, required): Tag name or UUID.
Outputs:
TagAssignmentResult
96. ovirt_host_tag_assign
Assigns an inventory tag to a hypervisor host.
Inputs:
host_name_or_id(string, required): Hypervisor host name or UUID.tag_name_or_id(string, required): Tag name or UUID.
Outputs:
TagAssignmentResult
97. ovirt_host_tag_unassign
Unassigns an inventory tag from a hypervisor host.
Inputs:
host_name_or_id(string, required): Hypervisor host name or UUID.tag_name_or_id(string, required): Tag name or UUID.
Outputs:
TagAssignmentResult
98. ovirt_host_bond_create
Creates a bonded network interface on a hypervisor host combining 2 or more physical interfaces. Supports active-backup, 802.3ad (LACP), balance-rr, and custom bond modes.
Inputs:
host_name_or_id(string, required): Hypervisor host name or UUID.bond_name(string, required): Name for the bond device (e.g.bond0).slaves(list[string], required): Physical NIC slave names (e.g.['eth1', 'eth2']).mode(string, optional, default: 'active-backup'): Bonding mode policy.
Outputs:
HostBondResult
99. ovirt_host_bond_delete
Deletes a network bond interface from a hypervisor host, releasing slave interfaces back to standalone mode. Protected by safe-mode confirmation (confirm=True).
Inputs:
host_name_or_id(string, required): Hypervisor host name or UUID.bond_name(string, required): Name of the bond to dismantle.confirm(bool, optional, default: False): Confirmation flag required in safe-mode.
Outputs:
HostBondResult
100. ovirt_user_tag_list
Lists inventory tags assigned to an oVirt / OLVM user.
Inputs:
user_name_or_id(string, required): Username or UUID of the user.
Outputs:
list[TagSummary]
101. ovirt_user_tag_assign
Assigns an inventory tag to an oVirt / OLVM user.
Inputs:
user_name_or_id(string, required): Username or UUID of the user.tag_name_or_id(string, required): Name or UUID of the inventory tag to assign.
Outputs:
TagAssignmentResult
102. ovirt_user_tag_unassign
Unassigns an inventory tag from an oVirt / OLVM user.
Inputs:
user_name_or_id(string, required): Username or UUID of the user.tag_name_or_id(string, required): Name or UUID of the inventory tag to unassign.
Outputs:
TagAssignmentResult
103. ovirt_host_upgrade_check
Checks if operating system or package updates are available for a hypervisor host. Triggers the oVirt / OLVM engine to query host package repositories via Ansible runner and updates the host's update_available flag.
Valid host statuses for upgrade check areup or non_operational. If called on a host in an unsupported state, the tool performs a pre-validation guard to guide the operator.
Inputs:
name_or_id(string, required): Display name or UUID of the hypervisor host.
Outputs (
HostUpgradeCheckResult):success: Whether the check was initiated successfully.host_id: Hypervisor host UUID.host_name: Hypervisor host name.status: Current host status (up,non_operational).update_available: Boolean indicating whether updates are available.message: Diagnostic outcome message.
104. ovirt_host_upgrade
Upgrades operating system packages and VDSM on a hypervisor host using the oVirt / OLVM host upgrade Ansible automation playbook.
Enterprise Safety Matrix ("Guard-Before-Act"):
Maintenance Gate: The host MUST be in
maintenancestatus before starting an upgrade. If the host isup, the operation is strictly rejected to ensure all running virtual machines have been migrated off the host first usingovirt_host_maintenance.Safe Mode Gate: Modifying action in Safe Mode: requires
confirm=TruewhenMCP_SAFE_MODE=true.
Inputs:
name_or_id(string, required): Display name or UUID of the hypervisor host.reboot(bool, optional, default: True): Whether to automatically reboot the hypervisor after the upgrade completes.confirm(bool, optional, default: False): Confirmation flag required in safe mode (MCP_SAFE_MODE=true).async_(bool, optional, default: True): Whether to execute the upgrade playbook asynchronously via the engine runner.timeout_minutes(int, optional, default: 60): Maximum duration in minutes for the upgrade playbook execution.
Outputs (
HostUpgradeResult):success: Whether the upgrade was initiated successfully.action:"upgrade".host_id: Hypervisor host UUID.host_name: Hypervisor host name.status: Current host status ("maintenance").reboot_requested: Whether automatic post-upgrade reboot is requested.message: Detailed execution status.
105. ovirt_system_events
Retrieves global audit log events, errors, warnings, alerts, and operational messages across the entire virtualization environment (hosts, VMs, storage domains, clusters). Supports filtering by severity level ('alert', 'error', 'warning', 'normal'), custom search queries, and pagination with max_events and from_event_id.
Inputs:
max_events(int, optional, default: 50): Maximum number of events to return (1 to 500).severity(string, optional): Filter by severity level ('normal','warning','error','alert').search(string, optional): Custom oVirt search expression (e.g.'type = ...', keywords, or entity filters).from_event_id(int, optional): Sequence event ID to fetch events starting after this event.
Outputs:
list[SystemEvent]id: Unique event sequence ID.code: Internal numeric event code.severity: Severity level (normal,warning,error,alert).time: Timestamp when the event occurred in ISO format.description: Human-readable audit message or diagnostic explanation.vm_name: Affected virtual machine name, if applicable.host_name: Affected hypervisor host name, if applicable.cluster_name: Affected cluster name, if applicable.storage_domain_name: Affected storage domain name, if applicable.user_name: Username who initiated or triggered the action, if applicable.correlation_id: Operation tracking correlation identifier.
Example Output:
[
{
"id": "3904",
"code": 30,
"severity": "normal",
"time": "2026-11-19 10:34:10.135000+00:00",
"description": "User admin@internal logged in from 192.0.2.20.",
"vm_name": null,
"host_name": null,
"cluster_name": null,
"storage_domain_name": null,
"user_name": "admin@internal",
"correlation_id": null
},
{
"id": "3903",
"code": 9920,
"severity": "alert",
"time": "2026-11-19 07:04:40.561000+00:00",
"description": "There is no full backup available, please run engine-backup to prevent data loss.",
"vm_name": null,
"host_name": null,
"cluster_name": null,
"storage_domain_name": null,
"user_name": null,
"correlation_id": null
}
]Connecting to AI MCP Clients
ovirt-mcp supports two primary deployment models:
Local Desktop Mode (
stdio): Claude Desktop launches the server on-demand on your local machine (via Docker or Python venv).24/7 Network Daemon Mode (
sse): The server runs continuously in background (on a home server, NAS, Proxmox, or cloud VM) as a classic Docker container. Any AI client (Claude Desktop, Cursor, LibreChat) connects over HTTP via Server-Sent Events (/sse).
Method 1: Docker Desktop for Claude (Zero-Install Setup)
No Python, C compiler, or virtual environment required on your workstation!
Step 1: Build the Docker Image
git clone https://github.com/gerilab/ovirt-mcp.git
cd ovirt-mcp
docker build -t ovirt-mcp .Step 2: Configure Claude Desktop
Locate your configuration file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonLinux:
~/.config/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
Add the ovirt server configuration:
{
"mcpServers": {
"ovirt": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e", "OVIRT_URL=https://olvm-engine.example.com/ovirt-engine/api",
"-e", "OVIRT_USERNAME=admin@internal",
"-e", "OVIRT_PASSWORD=YourSecurePasswordHere",
"-e", "OVIRT_INSECURE=true",
"-e", "MCP_COMPACT_MODE=true",
"ovirt-mcp"
]
}
}
}Restart Claude Desktop. The hammer icon will show all 107 oVirt tools loaded!
Method 2: Classic 24/7 Docker Container (Network SSE Daemon)
Run ovirt-mcp continuously in background on a central server (e.g. Proxmox LXC/VM, TrueNAS, unRAID, or dedicated Linux server). Multiple team members and AI clients connect to the shared instance over LAN without installing Docker on their local laptops.
Step 1: Start with Docker Compose
Clone the repository and copy the environment template:
git clone https://github.com/gerilab/ovirt-mcp.git
cd ovirt-mcp
cp .env.example .envEdit .env with your engine credentials:
OVIRT_URL=https://olvm-engine.example.com/ovirt-engine/api
OVIRT_USERNAME=admin@internal
OVIRT_PASSWORD=YourSecurePasswordHere
OVIRT_INSECURE=true
MCP_TRANSPORT=sse
MCP_PORT=8000Start the daemon in background:
docker compose up -d(Alternatively, without docker-compose):
docker run -d \
--name ovirt-mcp \
--restart unless-stopped \
-p 8000:8000 \
-e OVIRT_URL="https://olvm-engine.example.com/ovirt-engine/api" \
-e OVIRT_USERNAME="admin@internal" \
-e OVIRT_PASSWORD="YourSecurePasswordHere" \
-e OVIRT_INSECURE="true" \
-e MCP_TRANSPORT="sse" \
-e MCP_HOST="0.0.0.0" \
-e MCP_PORT="8000" \
ovirt-mcpStep 2: Check Logs and Health
docker logs -f ovirt-mcpOutput confirms:
INFO - Starting oVirt/OLVM MCP server in network daemon mode (transport='sse', bind='0.0.0.0:8000')...Step 3: Connect AI Clients via Network URL
Configure Claude Desktop or Cursor on any computer on your network:
{
"mcpServers": {
"ovirt": {
"url": "http://192.0.2.10:8000/sse"
}
}
}(Replace 192.0.2.10 with your central server's IP address).
Method 3: Native Python Virtual Environment
If you prefer running directly on your host operating system without Docker:
cd /automation/mcp/ovirt-mcp
source .venv/bin/activate
ovirt-mcpConfigure Claude Desktop:
{
"mcpServers": {
"ovirt": {
"command": "/automation/mcp/ovirt-mcp/.venv/bin/ovirt-mcp",
"env": {
"OVIRT_URL": "https://olvm-engine.example.com/ovirt-engine/api",
"OVIRT_USERNAME": "admin@internal",
"OVIRT_PASSWORD": "YourSecurePasswordHere",
"OVIRT_INSECURE": "true",
"MCP_COMPACT_MODE": "true"
}
}
}
}Testing & Quality Verification
Run the Interactive Live Diagnostic Runner
Verify your live oVirt/OLVM engine connection and test all tools against real hypervisor infrastructure:
python scripts/test_live_olvm.pyRun Automated Unit Tests
Unit tests execute without needing access to a live engine using mocked SDK interfaces:
pytest -v tests/unitCode Formatting and Strict Type Checking
All code follows strict Python typing and Ruff linting standards:
# Code formatting and linting
ruff check src tests scripts --fix
ruff format src tests scripts
# Strict static type analysis
mypy src testsTroubleshooting & FAQ
1. No valid profile found in credentials
Cause: oVirt and OLVM require an AAA authentication profile suffix.
Solution: Specify the full account format in
OVIRT_USERNAME. For the default local admin, useadmin@internal. For internal domain accounts, useuser@internal.
2. Invalid user credentials
Cause: Incorrect password or mismatched profile.
Solution: Verify the password in the engine web administration portal. Ensure the username matches the profile shown on the login screen.
3. Failed to build ovirt-engine-sdk-python: curl/curl.h: No such file or directory
Cause: Missing native C development headers for
libcurlorlibxml2.Solution:
Ubuntu/Debian:
sudo apt install -y libcurl4-openssl-dev libxml2-dev gccRHEL/Oracle Linux:
sudo dnf install -y libcurl-devel libxml2-devel gcc
4. Operation blocked: Server is in READ-ONLY mode
Cause: An action was attempted that would alter hypervisor state while
MCP_READ_ONLY=true.Solution: If mutations are intended, set
MCP_READ_ONLY=falsein.env.
5. Operation requires confirmation in Safe Mode
Cause: Destructive actions (like shutting down a VM) require confirmation.
Solution: Supply
confirm=Trueas a tool argument.
License
Apache License 2.0. See LICENSE for details.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Provides capabilities that let LLM agents perform a range of infrastructure management tasks.
Manage Vozora VPS servers, SSH keys, firewalls, DNS and usage from an AI agent.
Protocol-native energy infrastructure orchestration for AI data centers. Provides 46 MCP tools across 8 grid protocols (IEC-61850, DNP3, Modbus, OCPP, OpenADR, IEEE 2030.5, IEC 60870-5-104, ICCP) with 5 core API primitives: connect, dispatch, settle, comply, and intel. Enables AI agents to programmatically interact with substations, grid interfaces, and energy assets for real-time workload-grid coordination.
Linux VMs for AI agents: create VMs, run commands, edit files and open preview URLs.
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceEnables AI agents to manage HPE OneView infrastructure through the REST API, including server hardware operations, power control, profile management, and network/storage configuration.-
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to manage VMware vSphere virtual infrastructure through comprehensive operations including VM power control, snapshot management, resource monitoring, performance analytics, and bulk operations with built-in safety confirmations for destructive actions.-
- FlicenseNot gradedqualityCmaintenanceEnables AI agents to manage VMware vSphere infrastructure through 55 typed tools built on the govc CLI. It supports comprehensive operations including VM lifecycle management, snapshot control, datastore navigation, and networking configuration.5-
- FlicenseNot gradedqualityDmaintenanceEnables management of oVirt / Red Hat Virtualization environments via AI assistants, supporting VM lifecycle, power operations, snapshots, and infrastructure queries.-