Proxmox Mcp

proxmox-mcp

An MCP server that lets an AI client read and operate a Proxmox VE cluster, VMs, containers, and nodes, over plain API-token auth.

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. Status: WIP. The tool surface and the safety model are stable, but the package is still pre-1.0. The latest release is 0.11.0.

Website & docs → lidless.dev/proxmox-mcp

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": "00000000-0000-0000-0000-000000000000",
        "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](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 safe-write | Create a resource pool. Requires confirm: true. | | proxmox_update_pool | 2 safe-write | Add/remove guests or storage in a pool. Requires confirm: true. | | proxmox_delete_pool | 2 safe-write | Delete an empty resource pool. Requires confirm: true. | | proxmox_add_ha_resource | 2 safe-write | Place a VM/container under HA management. Requires confirm: true. | | proxmox_delete_ha_resource | 2 safe-write | Remove a guest from HA management. Requires confirm: true. | | proxmox_create_replication | 2 safe-write | Create a storage replication job to another node. Requires confirm: true. | | proxmox_delete_replication | 2 safe-write | Delete a replication job. Requires confirm: true. | | proxmox_rollback_snapshot | 3 destructive | Roll back a resource to a named snapshot. | | proxmox_destroy_resource | 3 destructive | Permanently delete an LXC or VM (DELETE /nodes/{node}/{type}/{vmid}). | | proxmox_cleanup_smoke_resources | 3 destructive | Dry-run or destroy smoke-prefixed LXC/QEMU guests from a smoke pool. | | proxmox_delete_snapshot | 3 destructive | Delete a named snapshot. | | proxmox_force_stop_resource | 3 destructive | Non-graceful hard stop of a running container or VM. | | proxmox_delete_volume | 3 destructive | Permanently delete a storage volume (backup, ISO, template, disk image). | | proxmox_node_power | 3 destructive | Reboot or shut down an entire node, taking down every guest on it. | | proxmox_delete_storage | 3 destructive | Remove a storage definition from the datacenter config. |

Reads (43): open; no flags required. Gated guest reads (4): guest file/path/directory/service inspection tools require confirm: true because they expose in-guest state through host-backed SSH. Safe writes (41): require confirm: true. The schema documents the gate on every tool. WriteGateError fires before any HTTP call. Destructive (8): require confirm: true + destructive: true + env PROXMOX_ENABLE_DESTRUCTIVE=1. All three gates must be satisfied; if any one is missing the tool throws WriteGateError before resolving the resource.

> Eight tools are destructive and can delete, hard-stop, or power off resources: proxmox_destroy_resource, proxmox_cleanup_smoke_resources, proxmox_rollback_snapshot, proxmox_delete_snapshot, proxmox_force_stop_resource, proxmox_delete_volume, proxmox_node_power, and proxmox_delete_storage. They are gated behind the PROXMOX_ENABLE_DESTRUCTIVE=1 process env flag and stay inert until you set it. See [SECURITY.md](SECURITY.md) and the [Safety](#safety) section.

Quickstart

Install globally or run on demand with npx:

npm install -g @solomonneas/proxmox-mcp
# or, no install:
npx -y @solomonneas/proxmox-mcp

Set the three required credential env vars (scrub real hosts and IPs out of any shared config):

export PROXMOX_URL=https://192.0.2.10:8006
export PROXMOX_TOKEN_ID=pve-admin@pam!api-token-1
export PROXMOX_TOKEN_SECRET=00000000-0000-0000-0000-000000000000

# Optional: skip TLS cert validation for homelab self-signed certs.
# Accepts true/1/yes (case-insensitive). Defaults to false.
export PROXMOX_TLS_INSECURE=false

Wire it into your MCP client (full per-client config in [Setup](#setup)):

# Claude Code
claude mcp add proxmox -s user -- npx -y @solomonneas/proxmox-mcp

Then ask your agent to list your cluster's containers. Reads work with nothing but the three credential vars; write and destructive tiers stay gated until you opt in.

> Note: the latest published version is 0.11.0. npx/npm install pins the published release; this repository may track ahead between releases.

Configuration

Set the following env vars. All three credential vars are required.

PROXMOX_URL=https://192.0.2.10:8006
PROXMOX_TOKEN_ID=pve-admin@pam!api-token-1
PROXMOX_TOKEN_SECRET=00000000-0000-0000-0000-000000000000

# Optional: skip TLS cert validation (homelab self-signed certs).
# Accepts true/1/yes (case-insensitive). Defaults to false.
PROXMOX_TLS_INSECURE=false

Trailing slashes on PROXMOX_URL are stripped. The token secret is registered with the redactor on startup and masked from all log + error output.

In-container exec env vars

The proxmox_exec, proxmox_read_file, and proxmox_write_file tools SSH to the Proxmox host (for LXC, via pct exec) or directly to the VM (for QEMU). All are optional; defaults derive from PROXMOX_URL.

| Env var | Default | Purpose | | --- | --- | --- | | PROXMOX_SSH_HOST | hostname from PROXMOX_URL | Proxmox host for pct exec | | PROXMOX_SSH_PORT | 22 | SSH port | | PROXMOX_SSH_USER | root | SSH user on Proxmox host | | PROXMOX_SSH_KEY | ~/.ssh/id_ed25519 | Key path for Proxmox host SSH | | PROXMOX_VM_SSH_USER | falls through to PROXMOX_SSH_USER | Default user for direct VM SSH | | PROXMOX_VM_SSH_KEY | falls through to PROXMOX_SSH_KEY | Default key for direct VM SSH | | PROXMOX_SSH_MAX_OUTPUT_BYTES | 1048576 | Max stdout bytes and max stderr byte

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: lidless-labs
• Source: lidless-labs/proxmox-mcp
• License: MIT
• Homepage: https://lidless.dev/proxmox-mcp

Install and usage instructions live in the source repository linked above.