oVirt MCP Server

Manage oVirt/RHV virtualization infrastructure via MCP. Provides 186 tools for VMs, hosts, clusters, networks, storage, templates, snapshots, disks, events, RBAC, quotas, and more. Use when the user asks to manage oVirt virtual machines, create/delete/modify VMs, check host status, manage storage domains, handle templates, configure networks, manage user permissions, view events/alerts, or any oVirt/RHV infrastructure operations. Triggers on "oVirt", "RHV", "virtual machine", "VM management", "storage domain", "cluster", "host management".

MCP server for oVirt/RHV virtualization management. 186 tools covering the full infrastructure lifecycle.

Version: 0.1.0 | License: MIT | Author: Joey Ma (@imjoey)

Quick Start

Install

bash

pip install ovirt-engine-mcp-server

Or from source:

bash

git clone https://github.com/imjoey/ovirt-engine-mcp-server.git
cd ovirt-engine-mcp-server
pip install -e .

Configure

Environment variables (recommended):

bash

export OVIRT_ENGINE_URL="https://ovirt-engine.example.com"
export OVIRT_ENGINE_USER="admin@internal"
export OVIRT_ENGINE_PASSWORD="your-password"

Or create a config.yaml:

yaml

OVIRT_ENGINE_URL: https://ovirt-engine.example.com
OVIRT_ENGINE_USER: admin@internal
# OVIRT_ENGINE_PASSWORD should be set via environment variable

Run

bash

ovirt-engine-mcp

Claude Desktop / OpenClaw Integration

json

{
  "mcpServers": {
    "ovirt": {
      "command": "ovirt-engine-mcp",
      "env": {
        "OVIRT_ENGINE_URL": "https://ovirt-engine.example.com",
        "OVIRT_ENGINE_USER": "admin@internal",
        "OVIRT_ENGINE_PASSWORD": "your-password"
      }
    }
  }
}

Docker

bash

docker build -t ovirt-engine-mcp-server .
docker run -e OVIRT_ENGINE_URL=... -e OVIRT_ENGINE_USER=... -e OVIRT_ENGINE_PASSWORD=... ovirt-engine-mcp-server

Architecture

text

MCP Client (Claude / OpenClaw / etc.)
        │  stdio (JSON-RPC)
        ▼
  MCP Server (server.py)
  ┌─────────────────────────────┐
  │  OvirtMCP (ovirt_mcp.py)    │  ← Core SDK wrapper (ovirtsdk4)
  │  186 methods               │
  ├─────────────────────────────┤
  │  Extension Modules:         │
  │  NetworkMCP · ClusterMCP    │
  │  TemplateMCP · DataCenterMCP│
  │  HostExtendedMCP            │
  │  StorageExtendedMCP         │
  │  DiskExtendedMCP            │
  │  EventsMCP · AffinityMCP    │
  │  RbacMCP · VmExtendedMCP    │
  │  TemplateExtendedMCP        │
  │  QuotaMCP · SystemMCP       │
  └─────────────────────────────┘
        │
        ▼
  oVirt Engine REST API

Error Handling

All errors return structured JSON with error code, message, and retry guidance:

Code	Retryable	Description
CONNECTION_ERROR	✅	Failed to connect to oVirt Engine
NOT_FOUND	❌	Requested resource not found
PERMISSION_DENIED	❌	Insufficient permissions
VALIDATION_ERROR	❌	Invalid input parameters
TIMEOUT	✅	Operation timed out
SDK_ERROR	✅	oVirt SDK internal error

Retry strategy: Only retry on retryable: true errors. Use exponential backoff (1s → 2s → 4s). NOT_FOUND and PERMISSION_DENIED require user intervention.

Available Tools

186 tools across 27 categories. Each reference file is self-contained with its own index:

File	Tools	Covers
vm.md	35	VM lifecycle, pools, checkpoints, snapshots
host.md	19	Host management, fencing, iSCSI
cluster.md	11	Clusters, CPU profiles
datacenter.md	5	Data centers
instance-types.md	2	Instance types
storage.md	16	Storage domains, connections, iSCSI bonds
disk.md	13	Disk lifecycle, snapshots, move, resize
network.md	16	Networks, VNIC profiles, QoS, MAC pools
template.md	8	Template lifecycle, disk/NIC lists
system.md	6	System info, jobs
events.md	11	Events, bookmarks, alerts
rbac.md	24	Users, groups, roles, permissions, tags, filters
quota.md	7	Data center quotas
affinity.md	13	Affinity groups and labels

Quick Category Reference

Category	Count	Key Tools
VM Core	9	vm_list, vm_create, vm_start, vm_stop, vm_delete
VM Extended	16	vm_migrate, vm_console, vm_cdrom_*, vm_watchdog_*, vm_pin_to_host
VM Pools	5	vm_pool_list, vm_pool_create, vm_pool_update, vm_pool_delete
VM Checkpoints	4	vm_checkpoint_list/create/restore/delete
Snapshots	4	snapshot_list/create/restore/delete
Disks Core	3	disk_list, disk_create, disk_attach
Disks Extended	9	disk_get, disk_resize, disk_move, disk_sparsify, disk_export
Networks	9	network_list/create/update/delete, nic_list/add/remove
VNIC Profiles	5	vnic_profile_list/create/update/delete/get
Network Filters & QoS	3	network_filter_list, mac_pool_list, qos_list
Hosts Core	3	host_list, host_activate, host_deactivate
Hosts Extended	16	host_add, host_fence, host_iscsi_*, host_install, host_nic_*
Clusters	10	cluster_list/create/update/delete, cluster_cpu_load, cluster_memory_usage
CPU Profiles	2	cpu_profile_list, cpu_profile_get
Data Centers	5	datacenter_list/create/update/delete/get
Storage Core	8	storage_list/create/delete/attach/detach/stats
Storage Extended	10	storage_refresh, storage_import_vm, storage_files, iscsi_bond_list
Templates Core	2	template_list, template_vm_create
Templates Extended	6	template_get/create/delete/update, template_disk_list, template_nic_list
Instance Types	2	instance_type_list, instance_type_get
Affinity Groups	7	affinity_group_list/create/update/delete/add_vm/remove_vm
Affinity Labels	6	affinity_label_list/create/delete/assign/unassign
Events	11	event_list, event_search, event_alerts/errors/warnings, event_summary
RBAC	24	user_*, group_*, role_*, permission_*, tag_*, filter_list
Quotas	7	quota_list/create/update/delete, quota_*_limit_list
System & Jobs	6	system_get, job_list, job_cancel, system_statistics

Common Workflows

Create VM from Template

text

1. template_list → find template ID
2. cluster_list → find cluster ID
3. template_vm_create(name, template, cluster, ...)
4. vm_start(name_or_id)

Migrate VM

text

1. vm_list(status="up") → find running VM
2. host_list() → find target host
3. vm_migrate(name_or_id, target_host)

Create Snapshot & Restore

text

1. snapshot_create(name_or_id, description="before-patch")
2. ... perform changes ...
3. snapshot_restore(name_or_id, snapshot_id)  # if needed

Storage Health Check

text

1. storage_list → list all domains
2. storage_stats(name_or_id) → check each domain
3. event_errors → check for storage-related errors

RBAC Audit

text

1. permission_list(resource_type="cluster", resource_id="...") → list perms
2. user_list → list users
3. tag_list → list tags

Requirements

• Python >= 3.10
• oVirt Engine 4.4+
• Dependencies: mcp>=1.0.0, ovirtsdk4>=4.6.0, pyyaml>=6.0, requests>=2.31.0, colorlog>=6.8.0

Development

bash

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Lint
ruff check src/ tests/

Related Projects

• oVirt — Open-source virtualization management
• ovirtsdk4 — Official oVirt Python SDK
• Model Context Protocol — The MCP specification