proxmox-mcp

Open source · MIT · Model Context Protocol

Talk to your Proxmox cluster.

proxmox-mcp connects Claude and other AI assistants to Proxmox VE. Ask about VMs, containers, storage, backups and the cluster in plain English, and let the assistant make changes when you allow it.

Get started Star on GitHub
docker pull ghcr.io/mattoddie/proxmox-mcp
Claude · proxmox
Why is the db VM so slow today?
proxmox_list_guestssearch: "db"proxmox_get_vm_stats104 · last hourproxmox_get_node_statuspve2
db-01 (VMID 104) runs on pve2, where IO wait has been at 38% since 9:00. Its disk is on local-zfs, which is 94% full, and three other busy guests share it.

pve3 is quiet, at 2% IO wait with plenty of free space. Want me to live-migrate db-01 there?
Yes, move it.
proxmox_migrate_vm104 → pve3 · online
Done. db-01 is now running on pve3 after a live migration with its disk (4 min, 41 ms of downtime). IO wait inside the VM is down to 1%. ✅
314tools
19toolsets
8guided prompts
1Docker container

Ask anything

Your cluster, in plain English.

The assistant picks the right tools, runs them against the Proxmox API and explains what it found. No clicking through the web UI node by node.

“Give me a health check of the cluster.”

get_cluster_statusget_ceph_statuslist_node_updates

“Which guests have no backup from this week? Back them up now.”

list_unbacked_guestsbackup_guests

“Find snapshots older than 30 days and how much space they hold.”

list_all_snapshots

“Clone the ubuntu-24 template as web-03 on pve3 and start it.”

clone_vmvm_power

“Which storage fills up first, and do any disks have SMART warnings?”

list_storagelist_disks

“Check free disk space inside the db VM.”

get_vmguest_exec

Broad coverage

314 tools across the whole datacenter.

Grouped into 19 toolsets you can switch on and off, so the assistant only sees what you need: 156 read, 107 write, 44 delete and 7 exec tools.

cluster15

Cluster overview, nodes and guests at a glance, datacenter options, corosync config, metric servers and bulk guest actions.

nodes49

Node status and statistics, services, network interfaces, DNS, time, updates and repositories, subscriptions, certificates and ACME, logs and node power.

vms20

QEMU virtual machines: status, configuration, power, create, clone, disks, migration, templates, cloud-init and statistics.

containers16

LXC containers: status, configuration, power, create, clone, volumes, migration, templates, interfaces and statistics.

agent13

The QEMU guest agent: OS, network and filesystem information from inside VMs, filesystem freeze/trim, and (with exec enabled) running commands and reading/writing files.

snapshots7

Snapshots of VMs and containers: list, create, roll back, describe and delete, plus a cluster-wide view of stale snapshots.

storage25

Storage definitions and usage, volumes and content, ISO/template downloads, storage discovery, physical disks, SMART, ZFS and LVM.

backup16

vzdump backup jobs, ad-hoc backups, backup listing and verification state, restores, pruning and guests without backups.

tasks5

Proxmox tasks (UPIDs): list, inspect, read logs, wait for and stop them.

access33

Users, groups, roles, ACLs, API tokens, authentication realms, effective permissions and two-factor authentication.

firewall21

Firewall rules, options, aliases, IP sets and security groups at datacenter, node and guest level, plus the firewall log.

ha15

High availability: status, HA resources, groups and rules, and HA-managed migration.

sdn18

Software-defined networking: zones, VNets, subnets, controllers, IPAM and DNS, and applying pending SDN changes.

ceph27

Ceph: health, OSDs, pools, monitors, managers, metadata servers, CephFS, flags and configuration.

pools5

Resource pools and their members.

replication6

Storage replication jobs, their status and logs.

notifications10

Notification targets (sendmail, SMTP, Gotify, webhooks) and matchers.

hardware12

PCI and USB devices, mediated devices, resource mappings, CPU models and QEMU capabilities.

raw1

A raw API escape hatch for anything the other tools don't cover. It is limited to GET requests unless writes are enabled.

read write delete exec ·Full tool reference →

Safe by default

It can look. It only touches when you say so.

Tools that aren't allowed aren't registered at all. The assistant can't see them, so it can't call them or be talked into calling them.

  • Read-only out of the box. Writes, deletes and in-guest exec are three separate switches.
  • Destructive tools are labelled, so your client asks before running them.
  • Least privilege on the Proxmox side too. Use an API token with only the roles you want to grant.
  • Bearer-token auth, a Host allow-list and a read-only, non-root container.
Read the security model →
read

156 tools, always on

list_guests · get_vm_stats · list_backups …
write

107 tools with PROXMOX_ALLOW_WRITES=true

vm_power · clone_vm · migrate_vm · backup_guests …
delete

44 tools with PROXMOX_ALLOW_DELETES=true as well

delete_vm · delete_snapshot · delete_backup …
exec

7 tools with PROXMOX_ALLOW_EXEC=true as well

guest_exec · guest_write_file · vm_monitor_command …

Works with your cluster

Proxmox VE 8 and 9, one node or many

  • Proxmox VE 9.x
  • Proxmox VE 8.x
  • Single node
  • Multi-node cluster
  • Ceph
  • ZFS & LVM
  • Proxmox Backup Server storage

API token or username and password. Self-signed certificates work out of the box. Guests are found by VMID on whichever node they're on. Compatibility →

Works with your assistant

Streamable HTTP or stdio

  • Claude Code
  • Claude Desktop
  • VS Code
  • Cursor
  • Codex
  • Any MCP client

Run it once and share it, or start it per session with docker run -i. Long tasks are awaited and return their log. Client setup →

Quick start

Up and running in three steps.

  1. 1

    Create an API token

    In the Proxmox web UI, open Datacenter → Permissions → API Tokens → Add. Give the token's user the roles it needs, such as PVEAuditor for read-only.

  2. 2

    Start the container

    curl -fsSLO https://raw.githubusercontent.com/mattoddie/proxmox-mcp/main/compose.yaml
curl -fsSL https://raw.githubusercontent.com/mattoddie/proxmox-mcp/main/example.env -o .env
# set PROXMOX_URL, PROXMOX_TOKEN_ID,
# PROXMOX_TOKEN_SECRET and MCP_AUTH_TOKEN in .env
docker compose up -d
  3. 3

    Connect your assistant

    claude mcp add --transport http proxmox \
  http://<docker-host>:8080/mcp \
  --header "Authorization: Bearer <token>"

    Then ask: “How's my cluster doing?”

Ready to talk to your cluster?

Free, open source and MIT licensed. Contributions and compatibility reports are welcome.

Read the docs Contribute