olvm-aiops
OfficialThis server provides governed, audited, primarily read-only AIops visibility into OLVM/oVirt 4.5 engines: inventory, health/capacity diagnosis, and event/job inspection.
List data centers, clusters, KVM hosts, storage domains, and VMs.
Get individual hosts, storage domains, and VMs, plus VM statistics.
Summarize VM capacity: VM count, configured vCPUs, host cores, and assignment ratio.
Run ranked health/RCA diagnoses for the engine, hosts, storage capacity, and VMs.
Inspect events by severity, paging,
after_index, andsince_minutes; list jobs by status.Track long-running operations and recent issues, with transient/superseded states handled.
Use MCP or CLI against configured engine targets with audit logging, budget guards, risk tiers, and output sanitization/redaction.
Use
undo_list/undo_applyfor recorded undo tokens, though this release has no engine writes to undo.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@olvm-aiops What's wrong with my hosts?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
OLVM AIops
Audit availability: Real writes require a committed
pendingaudit row and stop before contacting the platform if storage is unavailable. Reads and previews may continue with a warning; new audit rows store outcome summaries rather than full responses.
Disclaimer: Community-maintained open-source project. Not affiliated with, endorsed by, or sponsored by Oracle or the oVirt project. "Oracle", "Oracle Linux" and "oVirt" are trademarks of their owners. MIT licensed.
AI-powered operations for Oracle Linux Virtualization Manager (OLVM) and
oVirt 4.5, over the engine REST API, with a built-in governance harness —
an audit log that MCP and CLI calls both write to, a token/runaway budget guard,
and descriptive risk tiers. Built for teams that run OLVM (often next to another
hypervisor platform) and want an agent to answer "what needs attention?" with
evidence from the engine, not guesses. Built on httpx and the MCP SDK, not on the
pycurl-based engine SDK.
Read-only in this release: inventory, health, capacity and diagnosis. Engine actions are asynchronous — the engine answers
completelong before a VM or host reaches its target state — so write tools are held back until each can confirm its own outcome. Do NOT use for XCP-ng — use xcpng-aiops. Do NOT use for Proxmox VE — use proxmox-aiops.
What this tool does, and does not, decide
It reads an OLVM / oVirt engine accurately and records every call. It does
not decide what an agent may change — that belongs to the engine account you
connect it with. Give that account a read-only role (such as ReadOnlyAdmin) and
the engine itself enforces it.
The one thing the tool guarantees is that nothing is silent: every call, over
MCP and over the CLI alike, lands an audit row in ~/.olvm-aiops/audit.db.
Running a smaller / local model? See agent-guardrails.md for what the tool already guarantees and a ready-made system prompt for the rest.
Related MCP server: proxmox-monitor
What it answers
Question | Tool | CLI |
Is the engine itself healthy — certificates, backups, clock? |
|
|
What is wrong with my hosts? |
|
|
Is storage about to stop the engine creating disks? |
|
|
Why is this VM paused / not responding? |
|
|
How many VMs and configured vCPUs are on this engine, and what is their ratio to host cores? |
|
|
What happened recently? What is new since I last looked? |
|
|
What long-running operations failed? |
|
|
Inventory |
|
|
18 MCP tools: 16 reads and diagnoses, plus the harness's undo_list /
undo_apply (which have nothing to undo in a read-only release).
vm_list accepts a one-based page (CLI: olvm-aiops vm list --page 2). Keep
the same limit and search, then follow nextPage until it is null. Each
response includes page, returned, limit, truncated, and total: null:
the engine has no atomic total-count field. The tool orders by VM name unless
the search already specifies sortby; it adds an explicit asc direction to
bare sorts because live OLVM 4.5.5 engines returned an empty page without it.
Agents should request no more than 20 rows per call: a large MCP response can
be clipped before the model sees its continuation metadata. oVirt paging is stateless, so concurrent
VM changes can still duplicate or omit rows across requests; do not claim an
exact fleet total from a changing inventory.
vm_capacity_summary walks VM pages within the server and returns only aggregates:
VM count, configured vCPUs, physical host cores and assignment ratio. If a page
limit, duplicate ID, missing CPU topology or truncated host inventory prevents
a supported total, complete is false and affected totals are null.
snapshotConsistent is always false: a completed walk is not an atomic engine snapshot.
Each diagnosis ranks findings worst first; every finding carries the measured
signal, a cause, an action and an explicit rank. Transient states are not
reported as failures: a host the engine is installing or rebooting is "in
progress", alert 9000 on a host without fencing hardware is informational, and an
event the host, VM or data center has since recovered from is marked superseded.
Events older than 24 hours (events_window_hours) are history, not findings, and
every warning-or-worse event inside the window lands in exactly one diagnosis —
engine-wide alerts such as certificate expiry and missing backups included.
Built from a live engine, not from the docs
Every read was written against, and every fixture captured from, a live Oracle Linux Virtualization Manager 4.5.5-1.73.el9 engine with Keycloak enabled. Things that engine does, which this tool accounts for:
counts, sizes and flags arrive as JSON strings, timestamps as epoch-ms numbers;
an attached storage domain has no status in
/storagedomains— status is read from each data center's storage-domain collection;/jobsrefuses anysearchand returns jobs oldest first, so jobs are sorted here;the
timesearch on events is unusable (formats return all or nothing), whilefrom=<index>is an exact cursor — henceafter_indexand a client-sidesince_minutes;the cursor sorted newest first returns the newest events above it and skips the rest, so
after_indexreads oldest first;/ovirt-engine/services/healthanswers without a login, and a data center's old status alerts stay in the log after it recovers;login events print the SSO session id, which is redacted before events are returned.
Quick start
As a Claude Code plugin
One install gives an agent both the skill and the MCP server:
/plugin marketplace add AIops-tools/marketplace
/plugin install olvm-aiops@aiops-toolsThe MCP server is fetched with uv and pinned to the
package version this plugin declares, so an audit row can be traced back to the
code that wrote it. Credentials are still configured with olvm-aiops init — see below.
As an OpenClaw plugin
The same bundle is published on ClawHub, where one install delivers the skill and its MCP server together:
openclaw plugins install clawhub:@zw008/olvm-aiops
openclaw skills info olvm-aiops # expect: Visible to model: yesRestart the OpenClaw gateway afterwards so it loads the plugin. The MCP server is
fetched with uv, pinned to this exact release, so
uvx has to be on PATH — without it the skill still installs but reports
Visible to model: no. Credentials are configured exactly as below.
As a CLI or standalone MCP server
uv tool install olvm-aiops
olvm-aiops init # wizard: engine URL, username with profile, CA file, encrypted password
olvm-aiops doctor # verify config, encrypted store, login and engine version
olvm-aiops host health # first diagnosisinit writes ~/.olvm-aiops/config.yaml (non-secret connection details) and
stores the password encrypted in ~/.olvm-aiops/secrets.enc. Example:
targets:
- name: engine1
url: https://olvm-engine.example.com # the Administration Portal origin (FQDN)
username: admin@ovirt@internalsso # admin@internal on engines without Keycloak
ca_file: /etc/pki/olvm-engine-ca.pem # engine CA; keeps verify_ssl on
timeout: 30 # seconds per request; raise for busy enginesThe username includes its profile. Engine-setup enables Keycloak by default since
4.5.1, which makes the admin admin@ovirt@internalsso; engines without Keycloak use
admin@internal. Download the engine CA from
https://<engine>/ovirt-engine/services/pki-resource?resource=ca-certificate&format=X509-PEM-CA
and connect by FQDN — the engine certificate does not cover its IP address.
For non-interactive use (MCP server, CI, cron) export the master password so the store can be unlocked without a prompt:
export OLVM_AIOPS_MASTER_PASSWORD='your-master-password'Where that password then lives: an exported variable is readable by every process this shell starts and is recorded by shell history. On a shared or long-lived host, prefer the interactive prompt, or inject it from a secret manager for the life of the one command that needs it.
MCP client config
{
"mcpServers": {
"olvm-aiops": {
"command": "uvx",
"args": ["--from", "olvm-aiops", "olvm-aiops-mcp"],
"env": { "OLVM_AIOPS_MASTER_PASSWORD": "your-master-password" }
}
}
}Env-block caveat: MCP clients launch the server with a minimal environment — your shell profile's exports are not inherited. Put
OLVM_AIOPS_MASTER_PASSWORD(and, if you use them,OLVM_AIOPS_HOME/OLVM_AIOPS_CONFIG/OLVM_AUDIT_APPROVED_BY) in theenvblock above, or the encrypted store cannot be unlocked and every tool returns a teaching error.
Managing secrets
olvm-aiops secret set engine1 # prompts hidden for the account password
olvm-aiops secret list # names only, values never shown
olvm-aiops secret rm engine1
olvm-aiops secret rotate-password # re-encrypt under a new master password
olvm-aiops secret migrate # import a legacy plaintext .env, then retires itA legacy plaintext env var OLVM_<TARGET_NAME_UPPER>_PASSWORD is still honoured
as a fallback with a deprecation warning (migrate with olvm-aiops secret migrate).
Governance
Every MCP tool passes through @governed_tool, and every CLI command calls the MCP tool of the
same name. It records; it does not authorize.
Audit — every call (tool, params with secrets redacted, result, status, duration, risk tier, and any operator-supplied approver/rationale) lands in
~/.olvm-aiops/audit.db(relocate withOLVM_AIOPS_HOME).Budget / runaway guard — a safety backstop, not an authorization gate: cumulative call and wall-time caps plus a tight-loop circuit breaker (
OLVM_MAX_TOOL_CALLS,OLVM_MAX_TOOL_SECONDS,OLVM_RUNAWAY_MAX).Risk tier — a descriptive label on the audit row derived from
risk_level; it gates nothing.Output hygiene — all engine-returned text is sanitized and bounded before it reaches the agent; SSO session ids in login events are redacted.
支持范围 / Supported scope
Area | Read | Write |
Engine | health diagnosis (health check, clock, certificates, backups) | — |
Hosts | list / get / health diagnosis | — |
Storage domains | list / get (data-center-scoped status, capacity) / capacity diagnosis | — |
VMs | list / get / statistics / health diagnosis | — |
Data centers, clusters | list | — |
Events, jobs | list (severity, paging, | — |
缺功能?(Missing something?) Coverage is intentionally focused. Open an issue or PR at github.com/AIops-tools/OLVM-AIops — feature requests, contributions, and comments are all welcome.
Scope & caveats
Verification status: every read and all four diagnoses were run end to end against a live OLVM 4.5.5 engine with one KVM host, an NFS data domain and one VM. A user has since run the read-only tools against a small production engine with 8 hosts and an FC data domain, and their results matched the engine's own API — including a second run under a
ReadOnlyAdminaccount, where every read and all four diagnoses worked and the figures matched the Administration Portal. Not yet verified: iSCSI / Gluster domains, self-hosted engine deployments, engines without Keycloak, or engines past the scan limits. Seedocs/VERIFICATION.md.Engine only: no direct host (vdsm) access. Hosts, storage and VMs are seen the way the engine sees them.
No writes in this release. Start/stop/migrate, maintenance and snapshots are planned once each write can confirm its own outcome rather than the engine's immediate
complete.
Not for
XCP-ng (use xcpng-aiops), Proxmox VE (use proxmox-aiops), other hypervisors, NAS/storage appliances, backup suites, container clusters, or network devices.
License
Available Tools
18 toolscluster_listBRead-only
[READ] Clusters with compatibility version, CPU type and memory over-commit policy.
Args: limit: Rows to return, 1-1000 (default 100). target: Engine target name from config; omit to use the default.
Inputs: limit, target.
datacenter_listARead-only
[READ] Data centers with status (up, uninitialized, maintenance…) and compat version.
Args:
limit: Rows to return, 1-1000 (default 100); truncated says when more exist.
target: Engine target name from config; omit to use the default.
Inputs: limit, target.
engine_health_rcaARead-only
[READ] Problems with the engine itself, ranked worst first, in one call.
Reads the engine's health check, its version, its clock against this machine and
its summary counts, plus warning-or-worse events that name no host, VM or storage
domain: engine or CA certificate expiry, missing or failed engine backups, a
cluster failing its HA reservation. Those alerts appear in no other diagnosis, so
call this first for "is anything wrong". Event 10803 (a storage-pool vdsm command
failed) names no host and lands here: its cause names the command, which is the
subject — not the engine — and its severity is the event's own. Event 2024 is a record
that someone ran unlock_entity.sh by hand: it is low, and whatever the unlocked
entity then did wrong is reported by its own event. Report findings in rank order and
quote their signal.
Args: events_limit: Recent warning-or-worse events to correlate, 1-1000 (default 200). events_window_hours: Ignore events older than this many hours, 1-720 (default 24). target: Engine target name from config; omit to use the default.
Inputs: target, events_limit, events_window_hours.
event_listARead-only
[READ] Engine events at or above a severity, newest first.
To follow new events, pass the highest index you have already seen as
after_index: events after it come back OLDEST first (order), so repeat with the
highest index returned while truncated is true and nothing is skipped.
since_minutes keeps events from the last N minutes and sets scanTruncated when
older ones in the window may be missing. SSO session ids in login events are
redacted.
Args:
limit: Rows to return, 1-1000 (default 100); truncated says when more exist.
min_severity: One of normal, warning, error, alert (default normal).
page: Older pages of events (not combinable with since_minutes or after_index).
after_index: Only events with a higher index than this, oldest first.
since_minutes: Only events from the last N minutes (1-129600).
target: Engine target name from config; omit to use the default.
Inputs: page, limit, target, after_index, +2 more.
host_getARead-only
[READ] One KVM host by id (see host_list).
Args: host_id: Host id. target: Engine target name from config; omit to use the default.
Inputs: host_id (required), target.
host_health_rcaARead-only
[READ] What needs attention on KVM hosts, ranked worst first, in one call.
Combines host status and status detail, reinstall/update flags and recent
warning-or-worse events that name a host. Each finding has signal (what was
measured), cause, action and rank. Hosts that the engine is installing or
rebooting are reported as in progress, not failed; alert 9000 (power management
not verifiable) is informational on hosts without fencing hardware. A failed
guest-agent call (event 10802, a command starting with VmLogon or VmLogoff whose
message names the guest agent) is a problem of a guest, not of the host that ran the
call: it is reported low and carries vmCandidates, the VMs the engine reports on
that host. The same command failing for another reason stays a host finding. The event names no
VM, so present those as candidates to check, never as the affected VM; if that
envelope has an error, or scanTruncated is true, say the candidate list is
incomplete. Every event-10802 finding reports one vdsm command rather than the host's
own state, so its cause names the command; do not restate it as "this host is
failing" unless the host's status, external status or flags say so. It also carries
relatedVmEvents: the VM-level failures the engine logged within windowSeconds on
this host, which is where the operation's own failure is recorded (vm_health_rca
reports that half). They are paired on time alone — say "possibly the same operation",
never that the host finding is about a named VM; an empty list means none was logged,
not that none was looked for. Report findings in rank order and quote their signal.
Args: events_limit: Recent warning-or-worse events to correlate, 1-1000 (default 200). events_window_hours: Ignore events older than this many hours, 1-720 (default 24); older ones are counted in eventsOutsideWindow. target: Engine target name from config; omit to use the default.
Inputs: target, events_limit, events_window_hours.
host_listARead-only
[READ] KVM hosts with status, SPM role, memory and VM counts.
A field the engine did not report is null, never 0. For "what is wrong with my hosts" use host_health_rca instead of reading this list yourself.
Args:
limit: Rows to return, 1-1000 (default 100); truncated says when more exist.
search: Engine query language, e.g. "status=up" or "status!=up".
target: Engine target name from config; omit to use the default.
Inputs: limit, search, target.
job_listARead-only
[READ] Engine jobs (long-running operations) with status and duration.
Args: limit: Rows to return, 1-1000 (default 100). status: Only one status: started, finished, failed, aborted, unknown. target: Engine target name from config; omit to use the default.
Inputs: limit, status, target.
storage_capacity_rcaARead-only
[READ] Storage-domain problems ranked worst first, in one call.
Critical when free space is below the engine's critical blocker (the engine then
refuses new disks and snapshots); medium below the low-space warning, or when thin
disks are committed beyond capacity while space is low (low on its own); high when
an attached domain is inactive, unknown or mixed. Warning-or-worse events naming a
storage domain (for example "deactivated by system") are attached to it.
Unattached domains such as the default image repository are skipped. A domain whose
thresholds are unset (the engine reports 0) is reported low with its measured free
space: nothing — not the engine, not this tool — will warn before it fills, and how
full is too full is not recorded anywhere to read. Over-commit
on its own is a planning limit, and its signal carries actual use next to it: do
not report an over-committed domain as short of space unless a low-space or
blocker finding says so. Report findings in rank order and quote their signal.
Args: events_limit: Recent warning-or-worse events to correlate, 1-1000 (default 200). events_window_hours: Ignore events older than this many hours, 1-720 (default 24). target: Engine target name from config; omit to use the default.
Inputs: target, events_limit, events_window_hours.
storage_domain_getARead-only
[READ] One storage domain by id, with its data-center-scoped status.
Args: domain_id: Storage domain id (see storage_domain_list). target: Engine target name from config; omit to use the default.
Inputs: domain_id (required), target.
storage_domain_listARead-only
[READ] Storage domains with status and capacity (free, used, committed bytes and %).
The status of an attached domain comes from its data center (statusSource);
it is null — not guessed — when that could not be read (statusErrors).
Args:
limit: Rows to return, 1-1000 (default 100); truncated says when more exist.
target: Engine target name from config; omit to use the default.
Inputs: limit, target.
undo_applyADestructive
[WRITE][risk=medium] Apply a recorded undo by dispatching its inverse tool.
The inverse runs through its own governed tool, so it is audited under its own risk tier. Pass dry_run=True to preview the inverse call without executing it. A token can only be applied once.
Args:
undo_id: The undoId from undo_list (or an _undo_id in a write result).
dry_run: If True, preview the inverse tool + params without running it.
target: Passed through to the inverse tool when it accepts a target.
Inputs: undo_id (required), target, dry_run.
undo_listARead-only
[READ] List recorded, not-yet-applied undo tokens (most recent first).
Each entry names the original tool, the inverse tool that undo_apply
would run, and a human note. Use the undoId with undo_apply.
One extra row is read so truncated is measured rather than guessed from
the row count matching the limit; when it is true, older tokens exist.
Each entry carries effectVerified. False means the original write
lost its response, so the change it reverses is PROBABLE, not confirmed —
check the live state before applying, and do not report the result as a
restore of a state that may never have been reached.
Args: limit: Max rows to return (default 50, capped at 500). target: Unused (undo state is host-local); accepted for CLI uniformity.
Inputs: limit, target.
vm_capacity_summaryARead-only
[READ] Compact VM count, configured vCPUs, host cores and assignment ratio.
Walks VM pages inside the server; no VM rows enter the model context. A
completed walk is not an atomic snapshot if the inventory changes during it.
Missing CPU values, duplicate VM ids, or page/host limits make complete
false and prevent unsupported totals.
Args: page_size: VM rows per engine request, 1-1000 (default 100). max_pages: Maximum VM pages to walk, 1-100 (default 100). target: Engine target name from config; omit to use the default.
Inputs: target, max_pages, page_size.
vm_getBRead-only
[READ] One VM by id (see vm_list).
Args: vm_id: VM id. target: Engine target name from config; omit to use the default.
Inputs: vm_id (required), target.
vm_health_rcaARead-only
[READ] VM problems ranked worst first, in one call.
High for VMs stuck not_responding/unknown, paused (often storage I/O errors or a full domain — check storage_capacity_rca), or down with high availability; medium for image_locked; info for VMs mid-transition; low for config changes waiting for a restart. Recent warning-or-worse events naming a VM are attached to it, one finding per VM and code; an event is superseded (info) when the VM started after it, or when the engine reported it back up and it is up now. Down VMs without HA are normal. Report findings in rank order and quote their signal.
Args: events_limit: Recent warning-or-worse events to correlate, 1-1000 (default 200). events_window_hours: Ignore events older than this many hours, 1-720 (default 24); older ones are counted in eventsOutsideWindow. target: Engine target name from config; omit to use the default.
Inputs: target, events_limit, events_window_hours.
vm_listARead-only
[READ] VMs with status, host, vCPUs, memory and high-availability flag.
Args:
limit: Rows per page, 1-1000 (default 100); agents should use 20 or fewer
so the model sees the entire page and its continuation metadata.
search: Engine criteria, e.g. "status=up" or "cluster=Default"; omit page.
target: Engine target name from config; omit to use the default.
page: One-based page number (default 1). Follow nextPage until null.
Inputs: page, limit, search, target.
vm_statsARead-only
[READ] A VM's current statistics: memory, CPU %, network and disk usage, with units.
Args: vm_id: VM id. target: Engine target name from config; omit to use the default.
Inputs: vm_id (required), target.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Each tool targets a distinct resource+action, and the descriptions actively steer the agent away from overlap (host_list explicitly says to use host_health_rca for 'what is wrong with my hosts'; the four *_rca tools are scoped to disjoint signal sources — engine-only events, host-named events, VM-named events, storage-domain findings). Lists vs. get vs. stats vs. capacity-summary vs. RCA are cleanly separated, and undo_list/undo_apply are unambiguous.
Uniform snake_case with a resource-first, action-last pattern throughout: <resource>_list, <resource>_get, <resource>_health_rca, <resource>_capacity_rca, undo_apply. The only variation (storage_capacity_rca vs. storage_domain_list) is a resource qualifier, not a convention break, and it stays readable.
18 tools is slightly above the ideal 3-15 band, but each earns its place across four inventory domains plus one diagnostic and one control path; there is no filler. It reads as reasonable-but-heavy rather than bloated.
Read/observability coverage is thorough — datacenter, cluster, host, VM, storage domain, events, jobs, capacity, and per-domain RCA — with undo providing a reversal path for writes made elsewhere. The obvious gap is direct remediation (no vm_start/migrate, host_activate/maintenance, storage operations), so agents can diagnose but must act through tools outside this set.
Maintenance
Related MCP Connectors
Read-only MCP access to a documented IT fleet: state, changes, posture. 15 tools.
Read-only AI/LLM cost tools with current MCP discovery and attributable Registry transport.
Infrastructure context for any AI: VMware, Nutanix, Kubernetes and cloud. Read-only, off production.
Cloud cost, inventory and governance on AWS/Azure/GCP. Read-only by default, optional scoped writes
Related MCP Servers
AlicenseAqualityDmaintenanceRead-only MCP server that allows AI assistants to query and monitor KVM Fleet devices, audit logs, and console sessions through the official REST API.513 npm1MIT- FlicenseNot gradedqualityDmaintenanceProvides read-only Proxmox cluster oversight and configuration compliance checks through MCP, covering health, inventory, storage, backups, snapshots, and updates.-
- FlicenseNot gradedqualityAmaintenanceProvides authenticated read-only access to VMware Cloud Foundation Operations inventory, metrics, alerts, report definitions, targets, and skills via Streamable HTTP, with a durable audit trail and an admin UI.-
- AlicenseAqualityBmaintenanceEnables AI assistants to read Oracle Linux Virtualization Manager and oVirt inventory through the engine REST API, including VMs, hosts, and related details. It provides read-only tools for searching and retrieving VMs and KVM hosts.3Apache 2.0