proxmox-mcp

WIP

MCP server for Proxmox VE - manage VMs, containers, and nodes.

GitHub repo → npm: @solomonneas/proxmox-mcp →
42
tools exposed
3
write-gate tiers
stdio
MCP transport

WHAT IT DOES

Proxmox MCP exposes Proxmox VE to your AI client as a set of tools, authenticated with a Proxmox API token. Reads are open: cluster and node status, VM and container inventory, configs, storage, snapshots, backups, and usage. Mutations sit behind a three-tier write-gate, so a hallucinated tool call cannot power-cycle or delete a guest by accident. It is for homelab and small-cluster operators who want to inspect and drive Proxmox from an assistant without handing it an unguarded root session.

Status: work in progress. Published to npm as @solomonneas/proxmox-mcp; expect the surface to keep shifting while it stabilizes.

INSTALL

$ npm install -g @solomonneas/proxmox-mcp
 
# or run without installing
$ npx -y @solomonneas/proxmox-mcp

All three credential vars are required. Trailing slashes on the URL are stripped, and the token secret is masked from all log and error output.

# 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: homelab self-signed certs
PROXMOX_TLS_INSECURE=false
 
# required to unlock tier-3 destructive tools
PROXMOX_ENABLE_DESTRUCTIVE=1

TOOLS EXPOSED

42 tools across three gating tiers. Reads need no flag; safe writes and gated guest reads require confirm: true; destructive ops also require destructive: true plus the PROXMOX_ENABLE_DESTRUCTIVE=1 env flag.

Reads (20) · open

proxmox_status
proxmox_list_containers
proxmox_list_vms
proxmox_get_resource
proxmox_get_vm_config
proxmox_get_container_config
proxmox_recent_tasks
proxmox_list_backups
proxmox_resource_usage
proxmox_list_templates
proxmox_list_storage
proxmox_list_snapshots
proxmox_guest_network
proxmox_wait_task
proxmox_next_vmid
proxmox_list_pool_resources
proxmox_audit_permissions
proxmox_validate_qemu_smoke_source
proxmox_get_task_status
proxmox_get_task_log

Safe writes (13) · confirm: true

proxmox_start_resource
proxmox_stop_resource
proxmox_reboot_resource
proxmox_snapshot_resource
proxmox_run_backup
proxmox_create_container
proxmox_create_vm
proxmox_clone_resource
proxmox_exec
proxmox_write_file
proxmox_service_start
proxmox_service_stop
proxmox_service_restart

Gated guest reads (4) · confirm: true

proxmox_read_file
proxmox_stat_path
proxmox_list_directory
proxmox_service_status

Destructive (5) · confirm + destructive + env

proxmox_destroy_resource
proxmox_force_stop_resource
proxmox_rollback_snapshot
proxmox_delete_snapshot
proxmox_cleanup_smoke_resources

CLIENT CONFIG

Sample mcpServers entry (Claude Desktop / Claude Code / any MCP client). The same shape works in OpenClaw, Codex CLI, and Hermes; see the README for those formats.

{
  "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"
      }
    }
  }
}

Token-scope tip: start with a read-only token (Datastore.Audit + VM.Audit + Sys.Audit), confirm the read tools work, then grade up privileges only after verifying the secret is masked in your transcripts.