Skip to main content
Glama
Proxmox VE MCP server

Proxmox VE MCP server

Proxmox VE MCP server

Proxmox VE (Mojood Connect) MCP server

Ask Claude about your Proxmox VE in plain words: which guests no backup job covers, whose backups are overdue, which production VMs are stopped, what's going on with one VM. Start, shut down or reboot a guest and take snapshots from the same chat, with a confirmation step before anything changes. There is no tool that deletes a guest, restores a backup or rolls back a snapshot.

Built by Mojood Connect as a working demo for Proxmox. It runs against any Proxmox VE 8 or 9 through its REST API, with an API token. This repository includes a script that sets up a local Proxmox VE 9.2 (Proxmox's official arm64 build, in a VM on an Apple Silicon Mac) with SAMPLE guests for a made-up company, Harbor Trading, so you can try it without touching a real cluster.

Tools

Tool

What it does

Changes anything?

overview

Nodes (CPU, memory, uptime), storage use, guests running and stopped, backup jobs

No

find_guests

VMs and containers by name, id, tag or state, with CPU and memory in use

No

guest_details

One guest: cores, disks, notes, snapshots, last backup, whether a backup job covers it, recent tasks (who did what)

No

needs_attention

Guests in no backup job, overdue backups, stopped production guests, old snapshots, storage filling up, guests short of memory

No

power_guest

Start, shut down (cleanly) or reboot a VM or container

Yes, after confirmation

snapshot_guest

Take a snapshot, with a note saying who asked for it

Yes, after confirmation

How changes are made safe. A call to power_guest or snapshot_guest without a confirmation changes nothing: it returns a plain summary ("Start mail-relay (VM 104 on lima-pve, now stopped). It is tagged prod.") and a one-time code. The change happens only when the same request comes back with that code, within 10 minutes. A code works once, and only for the request it was issued for. The server's instructions tell the model to show the summary and wait for the user's yes. Proxmox's own task log records every change under the token's user.

Least privilege. The demo's token belongs to its own Proxmox user, claude@pve, with a custom role holding only VM.Audit, VM.PowerMgmt, VM.Snapshot, Datastore.Audit and Sys.Audit, plus VM.Backup and Datastore.AllocateSpace (on the backup storage only), because Proxmox lists a guest's backups only to users who could back it up. No tool makes, restores or deletes a backup.

Related MCP server: Proxmox MCP Server

Try it locally

Needs an Apple Silicon Mac (M3 or later, for nested virtualization) with Lima, uv and Python 3.13, about 6 GB of free memory and 40 GB of disk.

scripts/reset.sh                         # Proxmox VE 9.2 in a Lima VM (first run installs it), filled with SAMPLE guests
uv run --env-file .env proxmox-mcp       # MCP server on http://127.0.0.1:8008/mcp (Streamable HTTP)

scripts/up.sh installs Proxmox VE the way Proxmox's Debian 13 guide describes, adds a ZFS pool (on a file) so VMs and containers can be snapshotted, creates the claude@pve user and its token, and a read-only viewer@pve user for the web UI at https://127.0.0.1:8006. Secrets go only into the git-ignored .env and are never printed. The local certificate is self-signed, so .env sets PVE_VERIFY_TLS=0; keep it on for a real installation.

Claude Desktop: add this to claude_desktop_config.json (Settings › Developer), with the path to this folder:

{
  "mcpServers": {
    "proxmox": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/proxmox-mcp", "--env-file", "/path/to/proxmox-mcp/.env", "proxmox-mcp", "--stdio"]
    }
  }
}

Then ask: "Which servers aren't backed up?", "What's going on with erp-app?", "Snapshot erp-app before tonight's update, and start mail-relay again."

Your own Proxmox VE: create a user and an API token with the rights above (pveum user token add <user> <name> --privsep 0), then set PVE_URL, PVE_TOKEN_ID (user@realm!name), PVE_TOKEN_SECRET and PVE_SAMPLE=0.

The SAMPLE guests

Six VMs (Alpine Linux, really booting) and four LXC containers for Harbor Trading: an ERP database and app server, a file server, a mail relay that was left stopped, a retired CRM with a 96-day-old snapshot, a staging web server, two web containers, monitoring and a VPN gateway. A nightly backup job covers most of them but not all, and one guest's newest backup is 9.9 days old. Backups and snapshots are real; scripts/seed.sh moves a few of their timestamps back to give the estate a history. Everything in it is made up.

Tests

uv run --env-file .env pytest            # unit tests (a fake Proxmox API), plus live tests when the local Proxmox runs

What a production version adds

This demo uses one API token. A production server for Proxmox customers would add sign-in with each person's own Proxmox account (their realm, LDAP or OpenID), so Claude sees and does exactly what their roles allow; clusters with several nodes; Proxmox Backup Server; hosting with an audit log of every tool call; and a directory listing. That is what Mojood Connect builds.

License

Apache 2.0. Proxmox is a registered trademark of Proxmox Server Solutions GmbH; this project is not made or endorsed by Proxmox Server Solutions GmbH.

Available Tools

6 tools
find_guestsFind guestsC
Read-onlyIdempotent

VMs and containers with status, tags, CPU and memory in use now, and uptime.

Inputs: tag, kind, query, status. Returns: total, guests

guest_detailsA guest in detailB
Read-onlyIdempotent

One guest: status and use, cores and disks, notes, its snapshots, its last backup and whether a backup job covers it, and its recent tasks from Proxmox's task log (who did what, when).

Inputs: guest (required). Returns: cores, disks, guest, notes, +6 more

needs_attentionWhat needs attentionB
Read-onlyIdempotent

Guests no backup job covers, overdue backups, production guests that are stopped, old snapshots, storage filling up, and guests short of memory.

Inputs: backup_days. Returns: memory_high, old_snapshots, backups_overdue, storage_filling, +2 more

overviewOverviewB
Read-onlyIdempotent

Nodes (CPU, memory, uptime), storage use, how many guests run or are stopped, and the backup jobs.

Inputs: no named parameters. Returns: vms, nodes, running, stopped, +3 more

power_guestStart, shut down or reboot a guestA
Destructive

Start, cleanly shut down, or reboot a VM or container. The first call changes nothing and returns a summary and a confirmation code; it happens only on a second call with the code, after the user has said yes.

Inputs: guest (required), action (required), confirmation. Returns: done, guest, problem, summary, +2 more

snapshot_guestTake a snapshotA

Take a snapshot of a VM or container (it keeps running). The first call changes nothing and returns a summary and a confirmation code; the snapshot is taken only on a second call with the code, after the user has said yes.

Inputs: name (required), guest (required), description, confirmation. Returns: done, guest, problem, summary, +2 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 6 tools

    Disambiguation4/5

    Each tool targets a distinct concern: health triage (needs_attention), cluster-wide status (overview), guest listing (find_guests), single-guest drill-down (guest_details), power actions, and snapshots. The only mild overlaps are needs_attention vs overview (both aggregate health) and find_guests vs guest_details (list vs detail), but the descriptions make the boundaries clear enough.

    Naming Consistency3/5

    All names use snake_case, but the conventions are mixed: find_guests/power_guest/snapshot_guest are verb_noun, guest_details is noun_noun, and needs_attention/overview are bare noun phrases with no verb. It remains readable, but the pattern is not predictable across the set.

    Tool Count4/5

    Six tools is a reasonable, well-scoped set for a Proxmox monitoring/ops surface, and each tool clearly earns its place. It is on the lean side for a broad hypervisor domain, but not thin enough to be a problem.

    Completeness3/5

    Read paths (overview, guest listing/detail, attention scan) and two guarded write actions (power, snapshot) are covered, but major lifecycle operations are missing: create/clone/delete guest, backup job creation/run/restore, and storage or migration actions. An agent asked to provision or remove a VM, or manage backups, would hit a dead end.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers