proxmox-ops-mcp
Provides Ceph health checks in Proxmox environments, including health details with hints, OSD and placement group state, monitor quorum, and capacity information.
Provides operational tools for Proxmox VE, including cluster health, node and guest inventory, backup audits, storage and maintenance status, placement recommendations, evacuation planning, and guarded write operations such as power management, snapshots, and migration.
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., "@proxmox-ops-mcp Did every guest get backed up last night? Flag any that missed."
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.
proxmox-ops-mcp
An MCP server for Proxmox VE, built for operations work: finding out what is wrong with a cluster, whether the backups are actually there, and whether a node can be taken down for maintenance. Write access exists, but it is off by default and every change needs an explicit second call.
Why another Proxmox MCP server
The existing ones mostly expose the API endpoint by endpoint. That is fine for "start
VM 104", but questions like "which guests have no backup from last night?" then need
a dozen calls, and the model has to know Proxmox well enough to combine them correctly.
It usually doesn't. For example, it won't know that a token without VM.Backup gets an
empty backup list instead of an error.
This server puts that knowledge into the tools. backup_audit reads the backup volumes,
applies the same guest selection as vzdump jobs and checks whether the token is even
allowed to see the volumes. The model gets a list of findings back, each with a stable
code and a recommendation.
Related MCP server: proxmox-monitor
Status
Version 0.1, usable but young. What has been tested where:
Proxmox VE 9.2, single node, ZFS, two backup storages | all read tools, all write tools (on a throwaway VM in a dedicated pool) |
Multi-node clusters, HA, Ceph | unit and integration tests with realistic payloads only |
Proxmox VE 8, Proxmox Backup Server storages | not tested live yet; reports welcome |
The live tests found three things the API documentation doesn't mention, and the server handles each of them:
PVE 9 reports
cpuandwaitas 0 in the node status call.Backup listings come back empty, without an error, when the token lacks privileges.
/cluster/resourceslags a few seconds behind the real guest state.
Install
uvx proxmox-ops-mcp --version # run without installing (uv)
pipx install proxmox-ops-mcp # or as a CLI tool
docker pull ghcr.io/derdennis1012/proxmox-ops-mcpPython 3.11 or newer. From source: git clone … && uv sync && uv run proxmox-ops-mcp.
Setup
1. Create an API token. Read-only to start with:
pveum user add mcp@pve
pveum acl modify / --users mcp@pve --roles PVEAuditor
pveum user token add mcp@pve ops --privsep 1 # prints the secret once
pveum acl modify / --tokens 'mcp@pve!ops' --roles PVEAuditorWith only this role, backup_audit cannot see backups. Higher tiers need more
privileges, and Proxmox's ACL rules have a few traps. Both are covered in
docs/proxmox-setup.md.
2. Check the connection.
$ export PROXMOX_HOST=pve1.example.com PROXMOX_TOKEN_ID='mcp@pve!ops' PROXMOX_TOKEN_SECRET=…
$ uvx proxmox-ops-mcp check
OK connected to pve1.example.com:8006 as mcp@pve!ops
Proxmox VE 9.2.5 (release 9.2)
3 node(s) visible, access tier: read_onlyIf this fails with SSLError, the node certificate probably does not cover the address
you use. That is common when connecting over a VPN. check prints the command to pin
the certificate instead.
3. Add it to your client. Claude Code:
claude mcp add proxmox-ops \
-e PROXMOX_HOST=pve1.example.com \
-e PROXMOX_TOKEN_ID='mcp@pve!ops' \
-e PROXMOX_TOKEN_SECRET=… \
-- uvx proxmox-ops-mcpClaude Desktop, Cursor, VS Code, OpenAI Codex, Gemini CLI, Hermes Agent, OpenClaw and Docker: see docs/clients.md. It also covers what to watch out for when an autonomous agent uses the server.
Tools
Tool | Tier | |
| read_only | Quorum, offline nodes, CPU/memory, storage fill levels, HA errors |
| read_only | Ceph health checks with hints, OSD and PG state, monitor quorum, capacity |
| read_only | I/O wait, load, swap, memory/I/O pressure (PSI), version drift between nodes |
| read_only | Missing, stale and unscheduled backups; failed jobs; PBS verification |
| read_only | Failed tasks in a time window |
| read_only | ZFS pool state, device and data errors, scrub age, SMART, SSD wear |
| read_only | Pending Proxmox updates, needed reboots, expiring node certificates |
| read_only | Where a new guest fits, with a score and the reason for every node |
| read_only | Can a node be drained, what blocks it, and the commands to do it |
| read_only | Inventory, guest config (secrets redacted), task logs |
| operator | start, shutdown, reboot; |
| operator | Snapshot before a risky change |
| admin | Live migration for VMs, restart migration for containers |
Parameters and all finding codes: docs/tools.md.
Example, plan_node_evacuation(node="pve1"), shortened:
{
"feasible": true,
"summary": "pve1 can be drained: 3 guests to 2 target nodes, 1 container(s) with a brief restart.",
"guests": [
{ "vmid": 100, "name": "db01", "mode": "ha-managed", "target": "pve3" },
{ "vmid": 101, "name": "web01", "mode": "live-with-local-disks", "target": "pve2",
"warnings": ["local disks will be copied: scsi0@local-lvm"] },
{ "vmid": 200, "name": "dns01", "mode": "restart", "target": "pve3" }
],
"steps": [
"ceph osd set noout # prevent rebalancing while the node is down",
"ha-manager crm-command node-maintenance enable pve1 # HA moves its guests automatically",
"qm migrate 101 pve2 --online --with-local-disks",
"pct migrate 200 pve3 --restart",
"# perform maintenance on pve1, reboot, verify it rejoined the cluster",
"ha-manager crm-command node-maintenance disable pve1",
"ceph osd unset noout"
]
}Write access
PROXMOX_ACCESS_TIER is read_only unless you change it, and tools above the tier are
not registered at all. A write tool works in two steps:
Called normally, it checks the request against the live guest state and returns a preview of what would happen, plus a confirmation token.
Called again with the same arguments and that token, it executes.
The token works once, expires after five minutes and is bound to the exact parameters. That includes the node, so a guest that migrated in between invalidates it. Writes can additionally be limited to named pools or VMIDs and capped per hour. Every preview, execution and rejection is written to an audit log.
The token makes sure that what runs is what was previewed. It does not prove that a person approved it, because the model sees the token. Keep tool approval switched on in your MCP client for the write tools. There are no tools that delete anything.
The details, including the HTTP transport defaults, are in docs/security-model.md.
Configuration
Environment variables with the PROXMOX_ prefix: HOST, TOKEN_ID and TOKEN_SECRET
are required. Optional are ACCESS_TIER, CA_BUNDLE or TLS_FINGERPRINT, AUDIT_LOG
and a few more. A .env file is only read when passed with --env-file. The full list
is in docs/configuration.md.
Development
make install # uv sync + pre-commit
make check # ruff, mypy --strict, pytestThe diagnostic logic in src/proxmox_ops_mcp/analysis/ is plain functions over API
payloads and is tested without a cluster. tests/live/ runs read-only checks against a
real one if you point it at an env file. docs/architecture.md
explains the layout, and CONTRIBUTING.md explains how to contribute.
Documentation site: https://derdennis1012.github.io/proxmox-ops-mcp/. Planned next: direct Proxmox Backup Server checks (garbage collection, prune and verify jobs), replication jobs, guest snapshot hygiene.
License
MIT. Proxmox is a trademark of Proxmox Server Solutions GmbH; this project is not affiliated with it.
Available Tools
13 toolsbackup_auditBackup auditARead-onlyIdempotent
Find guests with missing or stale backups, unscheduled guests and failed jobs.
Reads backup volumes directly from every backup storage (including Proxmox Backup Server), so it reports what actually exists - not what the schedule promises. Set max_age_hours to match your schedule (e.g. ~170 for weekly backups). Failed tasks come from the cluster's recent task list, which only covers recent history.
Inputs: node, max_age_hours. Returns: Result of :func:`audit_backups`.
ceph_healthCeph health analysisARead-onlyIdempotent
Analyse Ceph: health checks, OSD up/in counts, PG states, monitor quorum, capacity.
Use for "why is Ceph degraded/warning?". Each Ceph health check becomes a finding with operator guidance.
Inputs: no named parameters. Returns: Result of :func:`analyze_ceph`.
cluster_healthCluster health checkARead-onlyIdempotent
Check quorum, node availability, CPU/memory pressure, storage fill levels and HA.
Start here for any "is something wrong with the cluster?" question. Findings are sorted worst-first and each carries a concrete recommendation.
Inputs: no named parameters. Returns: Result of :func:`analyze_cluster`.
compare_nodesCompare nodesARead-onlyIdempotent
Compare live CPU, I/O wait, load, memory, swap and versions across nodes.
Use for "why is node X slower than node Y?". Flags I/O-bound nodes, swapping, overload, version drift and memory imbalance.
Inputs: nodes. Returns: Result of :func:`compare_nodes`.
get_guestShow guest detailsARead-onlyIdempotent
Show one guest's live status and full configuration (secrets redacted).
Inputs: vmid (required). Returns: Result of ``get_guest``.
get_task_statusGet task status and logBRead-onlyIdempotent
Return the state of a Proxmox task and the tail of its log.
Inputs: node (required), upid (required), log_lines. Returns: Result of ``get_task_status``.
list_guestsList VMs and containersBRead-onlyIdempotent
List VMs and containers across the cluster with resource usage, tags and HA state.
Inputs: tag, node, status, guest_type, +1 more. Returns: Result of ``list_guests``.
list_nodesList cluster nodesARead-onlyIdempotent
List all cluster nodes with status, CPU and memory utilisation.
Inputs: no named parameters. Returns: Result of ``list_nodes``.
node_maintenance_statusUpdates, reboots and certificatesARead-onlyIdempotent
Show pending Proxmox updates, needed reboots and expiring node certificates.
A reboot is needed when a newer kernel is installed than the one running.
Covers the Proxmox package set (kernel, QEMU, ZFS, pve-*). Reflects apt's last package list refresh, which Proxmox runs daily.
Inputs: node. Returns: Result of :func:`analyze_upkeep`.
plan_node_evacuationPlan node evacuationARead-onlyIdempotent
Plan how to empty a node for maintenance without breaking HA or overloading others.
Detects passthrough devices, bind mounts, local disks, locks and HA-managed guests, assigns every guest a target and migration mode, and returns the exact command sequence (including Ceph 'noout' and HA maintenance mode). Executes nothing.
Inputs: node (required), memory_limit, exclude_targets. Returns: Result of :func:`plan_evacuation`.
recent_task_failuresRecent failed tasksARead-onlyIdempotent
List tasks that failed recently, grouped by type. Good first stop after an incident.
Based on the cluster-wide recent task list, which Proxmox keeps short; very old failures may no longer be included regardless of the window.
Inputs: hours, limit, task_type. Returns: Result of ``recent_task_failures``.
recommend_placementRecommend guest placementARead-onlyIdempotent
Rank nodes for a new VM/container by memory headroom, CPU load and vCPU over-commit.
Every node gets a score and the reasons it was accepted or rejected.
Inputs: cores (required), memory_gib (required), storage, disk_gib, +1 more. Returns: Result of :func:`recommend_placement`.
storage_healthStorage hardware healthARead-onlyIdempotent
Check ZFS pools and physical disks for anything that threatens data.
Covers pool state, device errors, data errors, fill level, scrub age, SMART health, SSD wear and bad sectors.
Use when asking whether the storage underneath the guests is healthy, or before maintenance on a node.
Inputs: node. Returns: Result of :func:`analyze_storage`.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Most tools target clearly distinct resources or diagnostic concerns: cluster, Ceph, storage, node comparison, guests, tasks, backups, placement, and evacuation. There is some overlap between cluster_health, ceph_health, and storage_health around storage fill and health checks, but descriptions mostly clarify that cluster_health is a broad first-stop while the others are focused deep dives.
All names use snake_case and are readable, but the naming convention is mixed: action-oriented names like list_nodes, compare_nodes, get_guest, recommend_placement, and plan_node_evacuation coexist with noun-based names like ceph_health, storage_health, cluster_health, backup_audit, and recent_task_failures. The inconsistency is understandable but prevents a fully predictable pattern.
Thirteen tools is well within a reasonable range for a broad Proxmox operations/diagnostics server. Each tool covers a distinct operational concern such as cluster health, storage health, backup auditing, placement, or evacuation planning, and none appears redundant.
The surface covers the main diagnostic and planning areas for Proxmox operations: cluster/node/Ceph/storage health, guest listing and inspection, task status and failures, backup auditing, maintenance status, placement recommendation, and evacuation planning. Minor gaps include network health, deeper HA state inspection, and any execution-oriented guest lifecycle operations, though the latter may be intentionally out of scope for this diagnostic/planning server.
Maintenance
Related MCP Connectors
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
Linux server administration over OAuth MCP: shell, Docker, systemd, files and monitoring.
Scans remote MCP servers for protocol, security, and TLS issues; exposes scan tools via MCP.
MCP deployment checks: required tools, schema drift and verifiable receipts. Free preflight.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables LLM agents to monitor and manage a Proxmox VE cluster, including cluster status, VM/container lifecycle, and node actions via MCP tools.8MIT
- FlicenseNot gradedqualityDmaintenanceProvides read-only Proxmox cluster oversight and configuration compliance checks through MCP, covering health, inventory, storage, backups, snapshots, and updates.-
- AlicenseAqualityCmaintenanceEnables MCP-compatible clients like Claude Desktop, Claude Code, Codex, and local-model hosts to inspect Proxmox VE clusters, nodes, VMs, containers, storage, snapshots, and tasks, with opt-in write operations for starting, stopping, cloning, backing up, and migrating guests. Read-only by default, it supports both stdio and Streamable HTTP transports.14MIT
- AlicenseBqualityCmaintenanceEnables natural-language access to Proxmox VE clusters for checking node, VM, storage, and task status and for performing confirmed VM power, clone, snapshot, configuration, and deletion operations through MCP clients.23MIT