NANDI Proxmox MCP

Turn your Proxmox cluster into an AI-driven platform with 140+ tools for automation, monitoring, and controlled execution.

Open source MCP server for Proxmox VE, powered by NANDI Services.

nandi-proxmox-mcp exposes Proxmox inventory, lifecycle, storage, backup, networking, firewall, access, monitoring, SSH diagnostics, and guarded remote/container operations without removing the safety rails needed for production clusters.

What stays enabled

• 140+ tools across nodes, cluster, QEMU, LXC, storage, backup, tasks, network, firewall, pools, access, templates, monitoring, and remote operations.
• Access tiers: read-only, read-execute, full.
• Module split: PVE_MODULE_MODE=core|advanced.
• Tool filters: PVE_CATEGORIES, PVE_TOOL_BLACKLIST, PVE_TOOL_WHITELIST.
• Destructive guardrails via confirm=true.
• Backward-compatible aliases such as listNodes, getVMStatus, startVM, stopContainer.
• stdio transport for MCP clients and Streamable HTTP transport for controlled remote deployments.

Required permissions

The server needs two trust channels and both are preserved intentionally:

• Proxmox API token
  • Used for inventory, lifecycle, configuration, and management endpoints.
  • Keep ACLs minimal: only grant the roles needed for the tools you actually enable.
• SSH batch access to the Proxmox host
  • Required for pct exec, batch SSH diagnostics, and container-level Docker inspection tools.
  • This is still necessary because Proxmox API coverage does not replace host-side pct and SSH-based diagnostics.

More detail: docs/PERMISSIONS.md

Destructive confirmations

Operations marked destructive do not execute unless the caller sends confirm=true.

Examples:

• VM/container stop, shutdown, reboot, suspend, delete, migrate, snapshot rollback
• storage/network/firewall/access writes that can alter cluster state
• advanced remote execution such as pve_exec_in_container

The server returns a structured CONFIRMATION_REQUIRED error when confirmation is missing. This behavior is unchanged and reinforced.

Access tiers

• read-only
  • Inventory, status, logs, metrics, and non-mutating diagnostics.
• read-execute
  • Read-only plus selected execution/lifecycle actions.
• full
  • Create, update, delete, migrate, restore, and admin-level operations.

PVE_MODULE_MODE=core hides advanced tools without renaming or removing canonical tool IDs from the codebase.

Runtime configuration

Environment variables

Required:

• PROXMOX_HOST
• PROXMOX_USER
• PROXMOX_REALM
• PROXMOX_TOKEN_NAME
• PROXMOX_TOKEN_SECRET
• PROXMOX_SSH_HOST
• PROXMOX_SSH_USER
• PROXMOX_SSH_KEY_PATH

Optional:

• PROXMOX_PORT default 8006
• PROXMOX_SSH_PORT default 22
• PROXMOX_ALLOW_INSECURE_TLS default false
• PVE_ACCESS_TIER=read-only|read-execute|full
• PVE_MODULE_MODE=core|advanced
• PVE_CATEGORIES
• PVE_TOOL_BLACKLIST
• PVE_TOOL_WHITELIST

HTTP transport:

• MCP_TRANSPORT=stdio|http
• MCP_HOST default 0.0.0.0
• MCP_PORT default 3000
• MCP_ALLOWED_HOSTS
• MCP_ALLOWED_ORIGINS
• MCP_RATE_LIMIT_WINDOW_MS
• MCP_RATE_LIMIT_MAX
• MCP_MAX_BODY_SIZE_BYTES
• MCP_HEADERS_TIMEOUT_MS
• MCP_REQUEST_TIMEOUT_MS
• MCP_KEEPALIVE_TIMEOUT_MS
• MCP_MAX_HEADERS_COUNT

Local config file

Setup writes .nandi-proxmox-mcp/config.json and .vscode/mcp.json.

The config loader now rejects:

• empty or malformed config paths
• oversized config files
• control characters in config paths

Quick start

Guided setup:

npx nandi-proxmox-mcp setup
npx nandi-proxmox-mcp doctor --check mcp-config,nodes,vms,cts,node-status,remote-op

Direct run with environment variables:

$env:PROXMOX_HOST="pve.local"
$env:PROXMOX_PORT="8006"
$env:PROXMOX_USER="svc_mcp"
$env:PROXMOX_REALM="pve"
$env:PROXMOX_TOKEN_NAME="nandi-mcp"
$env:PROXMOX_TOKEN_SECRET="<SECRET>"
$env:PROXMOX_SSH_HOST="pve.local"
$env:PROXMOX_SSH_

... [View full README on GitHub](https://github.com/NANDI-Services/proxmox-mcp#readme)