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

pip install ovirt-engine-mcp-server

Or from source:

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

Configure

Environment variables (recommended):

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:

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

Run

ovirt-engine-mcp

Claude Desktop / OpenClaw Integration

{
  "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

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

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:

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:

Quick Category Reference

Common Workflows

Create VM from Template

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

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

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

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

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

# 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