proxmox-mcp

<p align="center"> <img src="docs/assets/proxmox-mcp-social-preview.jpg" alt="proxmox-mcp banner" width="900"> </p> <p align="center"> <a href="https://lidless.dev"><img src="docs/assets/marks/proxmox-mcp-circle.png" width="48" alt="Lidless Labs"></a> </p> <h1 align="center">proxmox-mcp</h1> <p align="center"> <strong>An MCP server that lets an AI client read and operate a Proxmox VE cluster, VMs, containers, and nodes, over plain API-token auth.</strong> </p> <p align="center"> Why: your homelab lives in Proxmox, and you want an agent to inventory it, boot a guest, or trace a task without you clicking through the web UI. How it differs: a strict three-tier write gate is built into every tool, so reads are open but anything that changes state needs an explicit confirm flag, and anything destructive needs two more gates on top. <strong>Status: WIP.</strong> The tool surface and the safety model are stable, but the package is still pre-1.0. The latest release is <code>0.11.0</code>. </p> <p align="center"> <a href="https://lidless.dev/proxmox-mcp"><strong>Website &amp; docs &rarr; lidless.dev/proxmox-mcp</strong></a> </p> <p align="center"> <img src="https://shieldcn.dev/github/ci/lidless-labs/proxmox-mcp.svg?branch=master&workflow=ci.yml" alt="CI status"> <img src="https://shieldcn.dev/npm/@solomonneas/proxmox-mcp.svg" alt="npm version"> <img src="https://shieldcn.dev/badge/MCP-server-8A2BE2.svg" alt="MCP server"> <img src="https://shieldcn.dev/badge/license-MIT-green.svg" alt="MIT license"> </p>

What it does

proxmox-mcp is an open-source Model Context Protocol server for Proxmox VE, the open-source virtualization platform. It gives an AI client (Claude Desktop, Claude Code, OpenClaw, Codex CLI, or any MCP host) a structured, gated interface to a Proxmox cluster: inventory VMs and LXC containers, inspect node and storage status, read RRD metrics, trace tasks, manage snapshots and backups, run gated reads and shell commands inside guests, and provision, clone, or destroy resources, all over Proxmox API-token auth.

It is built for homelab and virtualization operators who want to point an agent at their cluster without handing it a root shell. The differentiator is the write-safety model: 96 tools split across four tiers, where reads need nothing, safe writes need confirm: true, and destructive operations need confirm: true + destructive: true + a process-level PROXMOX_ENABLE_DESTRUCTIVE=1 env flag. A hallucinated or careless tool call fails closed, before any HTTP traffic reaches Proxmox.

Proof

A real MCP client config. Drop this into Claude Desktop (claude_desktop_config.json) and the 96 tools appear in the client. Reads work immediately; the destructive env gate stays off until you opt in.

{
  "mcpServers": {
    "proxmox": {
      "command": "npx",
      "args": ["-y", "@solomonneas/proxmox-mcp"],
      "env": {
        "PROXMOX_URL": "https://192.0.2.10:8006",
        "PROXMOX_TOKEN_ID": "pve-admin@pam!api-token-1",
        "PROXMOX_TOKEN_SECRET": "REPL…[redacted]",
        "PROXMOX_TLS_INSECURE": "false"
      }
    }
  }
}

Tool list (96 tools, verified against source)

Tier markers below are authoritative: each tool's gate is enforced in code (src/gates.ts + per-tool schema), and WriteGateError fires before any HTTP call when a gate is unmet.

Generated from docs/assets/workflows/proxmox-safety.json with lidless workflow.

| Tool | Tier | Notes | | --- | --- | --- | | proxmox_status | 1 read | Cluster + node status. | | proxmox_list_containers | 1 read | LXC inventory across all nodes. | | proxmox_list_vms | 1 read | QEMU inventory across all nodes. | | proxmox_get_resource | 1 read | Single container or VM config + status by vmid. | | proxmox_get_vm_config | 1 read | QEMU VM config by vmid. | | proxmox_get_container_config | 1 read | LXC container config by vmid. | | proxmox_validate_qemu_smoke_source | 1 read | Preflight a QEMU VM before live smoke cloning. | | proxmox_audit_permissions | 1 read | Inspect effective permissions across smoke-relevant paths. | | proxmox_recent_tasks | 1 read | Recent UPID task list per node. | | proxmox_list_backups | 1 read | Backup inventory by storage. | | proxmox_resource_usage | 1 read | CPU/mem/disk RRD metrics. | | proxmox_list_templates | 1 read | LXC + VM templates available for cloning + container creation. | | proxmox_list_storage | 1 read | Storage status on one node or all nodes. | | proxmox_list_snapshots | 1 read | Snapshot inventory for one LXC or VM. | | proxmox_guest_network | 1 read | Guest network interfaces and usable IPv4 addresses. | | proxmox_wait_task | 1 read | Poll a UPID until stopped or timeout. | | proxmox_next_vmid | 1 read | Get the next available VMID for provisioning. | | proxmox_list_pool_resources | 1 read | Inspect resources assigned to a Proxmox pool, defaulting to mcp-smoke. | | proxmox_get_task_status | 1 read | Single UPID status lookup. | | proxmox_get_task_log | 1 read | Task log tail for a UPID. | | proxmox_list_storage_content | 1 read | List volumes on a storage: ISOs, templates, disk images, backups. | | proxmox_list_node_services | 1 read | Host systemd service states (pveproxy, pvedaemon, corosync). | | proxmox_list_disks | 1 read | Physical disks with model/size/SMART health/wearout. | | proxmox_list_updates | 1 read | Pending APT updates on a node (needs a Sys.Modify token). | | proxmox_list_firewall_rules | 1 read | Firewall rules at cluster/node/guest scope. | | proxmox_get_firewall_options | 1 read | Firewall enable state + default policy at a scope. | | proxmox_list_storage_config | 1 read | Datacenter storage definitions (id/type/content/nodes). | | proxmox_list_backup_jobs | 1 read | Scheduled vzdump backup jobs. | | proxmox_list_users | 1 read | Access users (userid, realm, enabled state). | | proxmox_list_roles | 1 read | Roles and their privileges. | | proxmox_list_acl | 1 read | ACL entries: who holds which role on which path. | | proxmox_list_pools | 1 read | All resource pools. | | proxmox_list_tokens | 1 read | API tokens for a user. | | proxmox_cluster_status | 1 read | Cluster membership + quorum per node. | | proxmox_ha_status | 1 read | HA manager status: quorum, fencing, resource states. | | proxmox_list_ha_resources | 1 read | HA-managed resources. | | proxmox_list_ha_rules | 1 read | HA rules (PVE 9+ replacement for HA groups). | | proxmox_list_replication | 1 read | Storage replication jobs. | | proxmox_list_sdn_zones | 1 read | SDN zones. | | proxmox_list_sdn_vnets | 1 read | SDN virtual networks. | | proxmox_list_metric_servers | 1 read | External metrics servers (InfluxDB/Graphite). | | proxmox_get_cluster_options | 1 read | Datacenter options (keyboard, MAC prefix, tags). | | proxmox_cluster_log | 1 read | Recent cluster-wide log entries. | | proxmox_read_file | 2 gated guest read | Read a file from inside an LXC or QEMU VM (SSH + cat). Requires confirm: true. | | proxmox_stat_path | 2 gated guest read | Inspect guest path metadata. Requires confirm: true. | | proxmox_list_directory | 2 gated guest read | List one guest directory. Requires confirm: true. | | proxmox_service_status | 2 gated guest read | Read systemd service state inside a guest. Requires confirm: true. | | proxmox_start_resource | 2 safe-write | Boot container or VM. Requires confirm: true. | | proxmox_stop_resource | 2 safe-write | Graceful shutdown. Requires confirm: true. | | proxmox_reboot_resource | 2 safe-write | Reboot in place. Requires confirm: true. | | proxmox_snapshot_resource | 2 safe-write | Create named snapshot. Requires confirm: true. | | proxmox_run_backup | 2 safe-write | Trigger vzdump for a vmid. Requires confirm: true. | | proxmox_create_container | 2 safe-write | Provision new LXC from template (POST /nodes/{node}/lxc). Requires confirm: true. | | proxmox_create_vm | 2 safe-write | Provision new QEMU VM (POST /nodes/{node}/qemu). Requires confirm: true. | | proxmox_clone_resource | 2 safe-write | Clone existing container or VM into a fresh vmid. Requires confirm: true. | | proxmox_exec | 2 safe-write | Run a shell command inside an LXC or QEMU VM. Returns stdout/stderr/exit_code. Requires confirm: true. | | proxmox_write_file | 2 safe-write | Write a text file (with parent dirs) inside an LXC or QEMU VM. Requires confirm: true. | | proxmox_service_start | 2 safe-write | Start a systemd service inside a guest. Requires confirm: true. | | proxmox_service_stop | 2 safe-write | Stop a systemd service inside a guest. Requires confirm: true. | | proxmox_service_restart | 2 safe-write | Restart a systemd service inside a guest. Requires confirm: true. | | proxmox_update_vm_config | 2 safe-write | Edit an existing QEMU VM config (cores/memory/net/etc, PUT .../qemu/{vmid}/config). Requires confirm: true. | | proxmox_update_container_config | 2 safe-write | Edit an existing LXC config (cores/memory/hostname/etc, PUT .../lxc/{vmid}/config). Requires confirm: true. | | proxmox_resize_disk | 2 safe-write | Grow a VM or container disk (PUT .../{type}/{vmid}/resize). Grow-only. Requires confirm: true. | | proxmox_restore_backup | 2 safe-write | Restore a vzdump/PBS archive into a VMID. Overwriting an existing VMID escalates to the destructive gate. Requires confirm: true. | | proxmox_migrate_resource | 2 safe-write | Migrate a VM or container to another node (POST .../migrate). Requires confirm: true. | | proxmox_suspend_resource | 2 safe-write | Suspend/pause a running guest (QEMU can hibernate to disk). Requires confirm: true. | | proxmox_resume_resource | 2 safe-write | Resume a suspended guest. Requires confirm: true. | | proxmox_reset_resource | 2 safe-write | Hard-reset a QEMU VM (reset button; no graceful shutdown). Requires confirm: true. | | proxmox_convert_to_template | 2 safe-write | Convert a stopped guest into a clone template (one-way). Requires confirm: true. | | proxmox_download_url | 2 safe-write | Download an ISO or container template from a URL onto a storage. Requires confirm: true. | | proxmox_cancel_task | 2 safe-write | Stop a running task by UPID (abort a stuck migration/backup). Requires confirm: true. | | proxmox_add_firewall_rule | 2 safe-write | Add a firewall rule at cluster/node/guest scope. Requires confirm: true. | | proxmox_delete_firewall_rule | 2 safe-write | Delete a firewall rule by position at a scope. Requires confirm: true. | | proxmox_set_firewall_enabled | 2 safe-write | Enable/disable the firewall at a scope. Requires confirm: true. | | proxmox_move_disk | 2 safe-write | Relocate a VM disk or container volume to another storage. Requires confirm: true. | | proxmox_create_storage | 2 safe-write | Define a new datacenter storage (dir/nfs/lvm/pbs/etc). Requires confirm: true. | | proxmox_create_backup_job | 2 safe-write | Create a scheduled vzdump backup job. Requires confirm: true. | | proxmox_delete_backup_job | 2 safe-write | Delete a scheduled backup job (archives untouched). Requires confirm: true. | | proxmox_set_acl | 2 safe-write | Grant or revoke a role for a user/token/group on a path. Requires confirm: true. | | proxmox_create_token | 2 safe-write | Create an API token; returns the secret once. Requires confirm: true. | | proxmox_delete_token | 2 safe-write | Revoke an API token. Requires confirm: true. | | proxmox_create_pool | 2 s