Skip to main content
Glama

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.

CI codecov PyPI License: MIT

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 cpu and wait as 0 in the node status call.

  • Backup listings come back empty, without an error, when the token lacks privileges.

  • /cluster/resources lags 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-mcp

Python 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 PVEAuditor

With 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_only

If 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-mcp

Claude 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

cluster_health

read_only

Quorum, offline nodes, CPU/memory, storage fill levels, HA errors

ceph_health

read_only

Ceph health checks with hints, OSD and PG state, monitor quorum, capacity

compare_nodes

read_only

I/O wait, load, swap, memory/I/O pressure (PSI), version drift between nodes

backup_audit

read_only

Missing, stale and unscheduled backups; failed jobs; PBS verification

recent_task_failures

read_only

Failed tasks in a time window

storage_health

read_only

ZFS pool state, device and data errors, scrub age, SMART, SSD wear

node_maintenance_status

read_only

Pending Proxmox updates, needed reboots, expiring node certificates

recommend_placement

read_only

Where a new guest fits, with a score and the reason for every node

plan_node_evacuation

read_only

Can a node be drained, what blocks it, and the commands to do it

list_nodes, list_guests, get_guest, get_task_status

read_only

Inventory, guest config (secrets redacted), task logs

guest_power

operator

start, shutdown, reboot; stop needs admin

create_snapshot

operator

Snapshot before a risky change

migrate_guest

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:

  1. Called normally, it checks the request against the live guest state and returns a preview of what would happen, plus a confirmation token.

  2. 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, pytest

The 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 tools
backup_auditBackup auditA
Read-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 analysisA
Read-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 checkA
Read-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 nodesA
Read-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 detailsA
Read-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 logB
Read-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 containersB
Read-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 nodesA
Read-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 certificatesA
Read-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 evacuationA
Read-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 tasksA
Read-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 placementA
Read-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 healthA
Read-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

    A3.8/5.0

    Scored across 13 tools

    Disambiguation4/5

    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.

    Naming Consistency3/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables LLM agents to monitor and manage a Proxmox VE cluster, including cluster status, VM/container lifecycle, and node actions via MCP tools.
      8
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides read-only Proxmox cluster oversight and configuration compliance checks through MCP, covering health, inventory, storage, backups, snapshots, and updates.
      -
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      14
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables 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.
      23
      MIT