mcp-proxmox

MCP server for Proxmox VE — read-only cluster, VM, container, storage, and network monitoring via the PVE REST API v2.

Features

• 44 read-only tools across 12 domains: Nodes, VMs, Containers, Storage, Cluster, Backup, Firewall, Diagnostics, Ceph, SDN, Pools, Replication
• PVEAPIToken authentication — no username/password, no session cookies
• Self-signed certificate support via PROXMOX_VERIFY_SSL=false
• Opportunistic Vault integration — loads secrets from HashiCorp Vault AppRole if configured
• 7 Claude Code skills for common operational workflows (/pve-health, /pve-inventory, etc.)
• stdio transport — compatible with Claude Desktop, Claude Code CLI, and any MCP-compliant host

Installation

npx (no install required)

npx @itunified.io/mcp-proxmox

Global install

npm install -g @itunified.io/mcp-proxmox
mcp-proxmox

Configuration

Set the following environment variables before starting the server:

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | PROXMOX_API_URL | Yes | — | PVE base URL, e.g. https://your-proxmox.example.com:8006 | | PROXMOX_TOKEN_ID | Yes | — | API token ID, e.g. admin@pam!monitoring | | PROXMOX_TOKEN_SECRET | Yes | — | API token UUID secret | | PROXMOX_VERIFY_SSL | No | true | Set false to allow self-signed certificates | | PROXMOX_TIMEOUT | No | 30000 | Request timeout in milliseconds |

Creating a PVE API Token

In the Proxmox web UI:

1. Go to Datacenter → Permissions → API Tokens
2. Create a token for a user with at least PVEAuditor role
3. Copy the token secret (shown only once)

Claude Desktop Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "proxmox": {
      "command": "npx",
      "args": ["@itunified.io/mcp-proxmox"],
      "env": {
        "PROXMOX_API_URL": "https://your-proxmox.example.com:8006",
        "PROXMOX_TOKEN_ID": "admin@pam!monitoring",
        "PROXMOX_TOKEN_SECRET": "your-token-secret",
        "PROXMOX_VERIFY_SSL": "false"
      }
    }
  }
}

Claude Code CLI Configuration

claude mcp add proxmox \
  --env PROXMOX_API_URL=https://your-proxmox.example.com:8006 \
  --env PROXMOX_TOKEN_ID=admin@pam!monitoring \
  --env PROXMOX_TOKEN_SECRET=your-token-secret \
  --env PROXMOX_VERIFY_SSL=false \
  -- npx @itunified.io/mcp-proxmox

Tools

Nodes (6 tools)

| Tool | Description | |------|-------------| | proxmox_node_list | List all nodes in the cluster with status, CPU, and memory info | | proxmox_node_status | Get detailed status of a specific node (CPU, memory, swap, rootfs, kernel) | | proxmox_node_resources | Computed resource utilization percentages (CPU%, memory%, disk%) with GB values | | proxmox_node_networks | List network interfaces on a node with optional type filter (bridge, bond, vlan) | | proxmox_node_disks | List physical disks on a node with model, size, serial, and health info | | proxmox_node_apt_updates | List available APT package updates on a node |

Virtual Machines — QEMU (5 tools)

| Tool | Description | |------|-------------| | proxmox_vm_list | List all QEMU VMs in the cluster, optionally filtered by node | | proxmox_vm_status | Get current runtime status of a VM (running, stopped, CPU, memory) | | proxmox_vm_config | Get VM configuration (hardware, network, disk, OS settings) | | proxmox_vm_snapshots | List all snapshots for a VM | | proxmox_vm_rrd | Get RRD performance data (CPU, memory, network, disk I/O) for a VM |

Containers — LXC (5 tools)

| Tool | Description | |------|-------------| | proxmox_ct_list | List all LXC containers in the cluster, optionally filtered by node | | proxmox_ct_status | Get current runtime status of a container (running, stopped, CPU, memory) | | proxmox_ct_config | Get container configuration (rootfs, network, OS, features) | | proxmox_ct_snapshots | List all snapshots for a container | | proxmox_ct_rrd | Get RRD performance data (CPU, memory, network, disk I/O) for a container |

Storage (4 tools)

| Tool | Description | |------|-------------| | proxmox_storage_list | List all storage configurations in the cluster | | proxmox_storage_status | Get status of a specific storage on a node (capacity, usage, availability) | | proxmox_storage_content | List content (volumes, backups, ISOs, templates) in a storage | | proxmox_storage_rrd | Get RRD performance data (read/write throughput, I/O ops) for a storage |

Cluster (4 tools)

| Tool | Description | |------|-------------| | proxmox_cluster_status | Get overall cluster status (quorum, nodes, cluster name) | | proxmox_cluster_resources | List all cluster resources (nodes, VMs, containers, storage) | | proxmox_cluster_tasks | List recent cluster-wide tasks with status and timing | | proxmox_cluster_log | Get cluster activity log (configuration changes, task events) |

Backup (2 tools)

| Tool | Description | |------|-------------| | proxmox_backup_list | List all backup files in a storage on a node | | proxmox_backup_detail | Get details for a specific backup file by volume ID |

Firewall (3 tools)

| Tool | Description | |------|-------------| | proxmox_fw_cluster_rules | List all firewall rules defined at the cluster level | | proxmox_fw_vm_rules | List firewall rules for a specific VM on a given node | | proxmox_fw_aliases | List all firewall aliases defined at the cluster level |

Diagnostics (4 tools)

| Tool | Description | |------|-------------| | proxmox_diag_version | Get PVE API version information | | proxmox_diag_subscription | Get subscription status for a node | | proxmox_diag_services | List all system services and their status on a node | | proxmox_diag_syslog | Read recent syslog entries from a node |

Ceph (4 tools)

| Tool | Description | |------|-------------| | proxmox_ceph_status | Get Ceph cluster status (returns info message if Ceph not installed) | | proxmox_ceph_osd_list | List all Ceph OSD entries (returns info message if Ceph not installed) | | proxmox_ceph_pool_list | List all Ceph storage pools (returns info message if Ceph not installed) | | proxmox_ceph_monitor_list | List all Ceph MON daemons (returns info message if Ceph not installed) |

SDN — Software-Defined Networking (3 tools)

| Tool | Description | |------|-------------| | proxmox_sdn_zones | List all SDN zones configured in the cluster | | proxmox_sdn_vnets | List all SDN virtual networks (VNets) | | proxmox_sdn_subnets | List all subnets within a specific SDN VNet |

Pools (2 tools)

| Tool | Description | |------|-------------| | proxmox_pool_list | List all resource pools defined in the cluster | | proxmox_pool_members | Get details and member resources for a specific pool |

Replication (2 tools)

| Tool | Description | |------|-------------| | proxmox_replication_list | List all replication jobs configured on a node | | proxmox_replication_status | Get the current status of a specific replication job |

Skills

Claude Code skills for common operational workflows:

| Skill | Command | Description | |-------|---------|-------------| | pve-health | /pve-health | Traffic-light cluster health dashboard (nodes, storage, Ceph, services) | | pve-inventory | /pve-inventory | Full VM/CT/resource inventory with VMID, name, type, status, node, CPU, RAM | | pve-backup-audit | /pve-backup-audit | Backup coverage audit — flags VMs with no backup or stale backups (>7 days) | | pve-resources | /pve-resources | CPU/RAM overcommit analysis — flags >2x CPU or >1.5x RAM overcommit | | pve-network | /pve-network | Network topology — bridges, VLANs, and VM/CT assignments | | pve-snapshot-audit | /pve-snapshot-audit | Snapshot age audit — flags snapshots older than 7 days, sorted by age | | pve-updates | /pve-updates | Available APT updates + subscription status + current PVE version |

License

AGPL-3.0-or-later — see LICENSE for details.