oVirt MCP Server#

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:

CodeRetryableDescriptionCONNECTION_ERROR✅Failed to connect to oVirt EngineNOT_FOUND❌Requested resource not foundPERMISSION_DENIED❌Insufficient permissionsVALIDATION_ERROR❌Invalid input parametersTIMEOUT✅Operation timed outSDK_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:

FileToolsCoversvm.md35VM lifecycle, pools, checkpoints, snapshotshost.md19Host management, fencing, iSCSIcluster.md11Clusters, CPU profilesdatacenter.md5Data centersinstance-types.md2Instance typesstorage.md16Storage domains, connections, iSCSI bondsdisk.md13Disk lifecycle, snapshots, move, resizenetwork.md16Networks, VNIC profiles, QoS, MAC poolstemplate.md8Template lifecycle, disk/NIC listssystem.md6System info, jobsevents.md11Events, bookmarks, alertsrbac.md24Users, groups, roles, permissions, tags, filtersquota.md7Data center quotasaffinity.md13Affinity groups and labels

Quick Category Reference#

CategoryCountKey ToolsVM Core9vm_list, vm_create, vm_start, vm_stop, vm_deleteVM Extended16vm_migrate, vm_console, vm_cdrom_*, vm_watchdog_*, vm_pin_to_hostVM Pools5vm_pool_list, vm_pool_create, vm_pool_update, vm_pool_deleteVM Checkpoints4vm_checkpoint_list/create/restore/deleteSnapshots4snapshot_list/create/restore/deleteDisks Core3disk_list, disk_create, disk_attachDisks Extended9disk_get, disk_resize, disk_move, disk_sparsify, disk_exportNetworks9network_list/create/update/delete, nic_list/add/removeVNIC Profiles5vnic_profile_list/create/update/delete/getNetwork Filters & QoS3network_filter_list, mac_pool_list, qos_listHosts Core3host_list, host_activate, host_deactivateHosts Extended16host_add, host_fence, host_iscsi_*, host_install, host_nic_*Clusters10cluster_list/create/update/delete, cluster_cpu_load, cluster_memory_usageCPU Profiles2cpu_profile_list, cpu_profile_getData Centers5datacenter_list/create/update/delete/getStorage Core8storage_list/create/delete/attach/detach/statsStorage Extended10storage_refresh, storage_import_vm, storage_files, iscsi_bond_listTemplates Core2template_list, template_vm_createTemplates Extended6template_get/create/delete/update, template_disk_list, template_nic_listInstance Types2instance_type_list, instance_type_getAffinity Groups7affinity_group_list/create/update/delete/add_vm/remove_vmAffinity Labels6affinity_label_list/create/delete/assign/unassignEvents11event_list, event_search, event_alerts/errors/warnings, event_summaryRBAC24user_*, group_*, role_*, permission_*, tag_*, filter_listQuotas7quota_list/create/update/delete, quota_*_limit_listSystem & Jobs6system_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