proxmox-mcp

proxmox-mcp

MCP server exposing your Proxmox VE cluster to Claude Code via the Proxmox REST API.

1. Create a Proxmox API token

On the Proxmox host (or via the web UI):

# Create a dedicated user
pveum user add mcp@pve

# Create a role with the permissions needed for this server.
# Start with PVEVMAdmin (covers create/clone/start/stop for VMs and CTs)
# plus PVEAuditor (read-only access to nodes/storage).
pveum aclmod / -user mcp@pve -role PVEVMAdmin
pveum aclmod / -user mcp@pve -role PVEAuditor

# Create an API token for that user (copy the secret shown, it's only displayed once)
pveum user token add mcp@pve mcp-token --privsep 0

This gives the token the same permission scope as the user. --privsep 0 means thetoken inherits the user's full permissions (simpler). Set --privsep 1 and assignACLs to the token specifically if you want tighter scoping.

Note on "no delete" by design: the role above does not grant VM.Allocateremoval/destroy actions are still possible under PVEVMAdmin in some Proxmoxversions — if you want to be stricter, create a custom role excludingVM.Config.* removal privileges. This server itself does not expose a destroytool, but a sufficiently broad token could still be used for destructive actionsvia raw API calls if compromised. Keep the secret safe.

2. Configure environment variables

export PROXMOX_HOST="https://192.168.100.10:8006"   # your Proxmox node, port 8006
export PROXMOX_TOKEN_ID="mcp@pve!mcp-token"
export PROXMOX_TOKEN_SECRET="<the-uuid-secret-from-step-1>"
export PROXMOX_TLS_INSECURE="true"  # set if using the default self-signed cert

Put these in a .env file or your shell profile — do not commit them.

3. Build

npm install
npm run build

4. Register with Claude Code

Add to your Claude Code MCP config (e.g. ~/.config/claude-code/mcp.json or viaclaude mcp add):

{
  "mcpServers": {
    "proxmox": {
      "command": "node",
      "args": ["/absolute/path/to/proxmox-mcp/dist/index.js"],
      "env": {
        "PROXMOX_HOST": "https://192.168.100.10:8006",
        "PROXMOX_TOKEN_ID": "mcp@pve!mcp-token",
        "PROXMOX_TOKEN_SECRET": "your-secret-here",
        "PROXMOX_TLS_INSECURE": "true"
      }
    }
  }
}

Run this on a machine with network access to your Proxmox API (VLAN 100 orwherever 192.168.100.x is reachable — e.g. your workstation on VLAN 10, oran LXC you SSH into).

Available tools

There is intentionally no destroy/delete tool. Removing VMs/CTs should bedone directly in the Proxmox UI.

Notes

• VMIDs must be unique cluster-wide — check list_resources before creating.
• net0 strings follow Proxmox syntax, e.g.name=eth0,bridge=vmbr0,ip=192.168.100.50/24,gw=192.168.100.1 for static IPon VLAN 100, or ip=dhcp for DHCP.
• For LXC templates, download them first via pveam available / pveam downloadon the node, or via the Proxmox UI (Storage → CT Templates).