proxmox-mcp

MCP server exposing Proxmox VE read + safe-write + destructive tools via API token auth. Three-tier write gating: reads are open, writes require confirm: true, destructive ops require confirm: true + destructive: true + a process-level PROXMOX_ENABLE_DESTRUCTIVE=1 env flag.

Tools

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_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_start_resource	2 safe-write	Boot container or VM.
proxmox_stop_resource	2 safe-write	Graceful shutdown.
proxmox_reboot_resource	2 safe-write	Reboot in place.
proxmox_snapshot_resource	2 safe-write	Create named snapshot.
proxmox_run_backup	2 safe-write	Trigger vzdump for a vmid.
proxmox_create_container	2 safe-write	Provision new LXC from template (POST /nodes/{node}/lxc).
proxmox_create_vm	2 safe-write	Provision new QEMU VM (POST /nodes/{node}/qemu).
proxmox_clone_resource	2 safe-write	Clone existing container or VM into a fresh vmid.
proxmox_destroy_resource	3 destructive	Permanently delete an LXC or VM (DELETE /nodes/{node}/{type}/{vmid}).
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_get_task_status	1 read	Single UPID status lookup.
proxmox_get_task_log	1 read	Task log tail for a UPID.

Reads (10): open; no flags required. Safe writes (8): require confirm: true. Schema documents the gate on every tool. WriteGateError fires before any HTTP call. Destructive (3): require confirm: true + destructive: true + env PROXMOX_ENABLE_DESTRUCTIVE=1. All three gates must be satisfied; any one missing throws WriteGateError before resolving the resource.

Configuration

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

PROXMOX_URL=https://pve.example.local: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.

Install

npm install -g @solomonneas/proxmox-mcp

Or run via npx:

npx -y @solomonneas/proxmox-mcp

Setup

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "proxmox": {
      "command": "npx",
      "args": ["-y", "@solomonneas/proxmox-mcp"],
      "env": {
        "PROXMOX_URL": "https://pve.example.local:8006",
        "PROXMOX_TOKEN_ID": "pve-admin@pam!api-token-1",
        "PROXMOX_TOKEN_SECRET": "00000000-0000-0000-0000-000000000000",
        "PROXMOX_TLS_INSECURE": "false"
      }
    }
  }
}

Claude Code

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

Then export env vars in your shell (~/.bashrc, ~/.zshrc) or pass --env flags.

OpenClaw

Plugin loads automatically once installed. Config goes in your ~/.openclaw/openclaw.json plugins.entries.proxmox (or use the bundled openclaw.plugin.json):

{
  "plugins": {
    "entries": {
      "proxmox": {
        "package": "@solomonneas/proxmox-mcp",
        "activation": { "onStartup": true }
      }
    }
  }
}

Env vars from ~/.openclaw/workspace/.env are inherited by the plugin.

Hermes Agent

Add to ~/.config/hermes/agents.yaml:

mcp_servers:
  proxmox:
    command: npx
    args: ["-y", "@solomonneas/proxmox-mcp"]
    env:
      PROXMOX_URL: https://pve.example.local:8006
      PROXMOX_TOKEN_ID: pve-admin@pam!api-token-1
      PROXMOX_TOKEN_SECRET: 00000000-0000-0000-0000-000000000000
      PROXMOX_TLS_INSECURE: "false"

Codex CLI

~/.codex/config.toml:

[mcp_servers.proxmox]
command = "npx"
args = ["-y", "@solomonneas/proxmox-mcp"]

[mcp_servers.proxmox.env]
PROXMOX_URL = "https://pve.example.local:8006"
PROXMOX_TOKEN_ID = "pve-admin@pam!api-token-1"
PROXMOX_TOKEN_SECRET = "00000000-0000-0000-0000-000000000000"
PROXMOX_TLS_INSECURE = "false"

Safety

This MCP uses the same three-tier write-gating pattern as the rest of the solomonneas/*-mcp family:

• Tier 1 (reads): open. No confirm flag needed. Status, listings, usage, recent tasks, backup inventory, template inventory.
• Tier 2 (safe writes): require an explicit confirm: true arg. The JSON schema documents this on every write tool. Start, stop, reboot, snapshot create, run backup, create container, create VM, clone live here. A hallucinated tool call without the confirm flag throws WriteGateError before any HTTP traffic.
• Tier 3 (destructive): require confirm: true + destructive: true + the env flag PROXMOX_ENABLE_DESTRUCTIVE=1 on the MCP process. Permanent resource deletion, snapshot deletion, and non-graceful force-stop live here.

Destructive operations env gate

Tier 3 destructive tools (proxmox_destroy_resource, proxmox_delete_snapshot, proxmox_force_stop_resource) require an additional safety gate beyond the per-tool confirm: true + destructive: true args: the env var PROXMOX_ENABLE_DESTRUCTIVE=1 must be set on the MCP process. Without it, the tools throw WriteGateError before any HTTP call is made.

This is intentional: destructive ops are rare. The env flag is a coarse "I am actively doing smoke-test cycles" toggle. Leave it unset day-to-day; flip it only when actively destroying resources is part of the workflow.

API token scope recommendation: start with a read-only token (PVE Datastore.Audit + VM.Audit + Sys.Audit) and verify the read tools work end-to-end. Grade up to write privileges (VM.PowerMgmt, VM.Snapshot, VM.Backup) only after you've confirmed the redactor is masking your secret in your transcripts and that the model is honoring the confirm gate. Tokens are tied to a PVE user and can be revoked instantly from the Datacenter > Permissions > API Tokens UI.

The PROXMOX_TLS_INSECURE=true toggle exists for homelab self-signed certs. Leave it false in any environment with a real CA-signed cert.

License

MIT