proxmox-ai

MCP server that lets an AI agent administer Proxmox VE in natural language, without ever giving it more power than strictly necessary.

"¿Qué contenedores están ejecutándose?"        → responde
"¿Cuál está consumiendo más RAM?"              → responde
"Reinicia el CT 105"                           → propone, espera confirmación, ejecuta
"Haz rollback del snapshot pre-update"         → exige una frase literal del humano
"Borra el CT 105"                              → no existe esa herramienta

The design starts from an idea: the model proposes, the policy engine decides, and the audit log remembers.

Status

Phase 1 (read-only) implemented and tested. Phases 2 through 5 are implemented but disabled by default: they are enabled one at a time with environment variables, and each one also needs its own privilege in the Proxmox ACL. See docs/roadmap.md.

Quick install

On the Proxmox node, create the dedicated user and token:

./scripts/setup-proxmox-user.sh

Copy the token secret: Proxmox won't show it again.

In the container where the MCP will live (see docs/instalacion.md to create it):

git clone https://github.com/dallaswk/proxmox-ai.git
cd proxmox-ai
python3 -m venv .venv && . .venv/bin/activate
pip install -e .

cp .env.example .env && chmod 600 .env
$EDITOR .env          # PROXMOX_HOST, PROXMOX_TOKEN_ID, PROXMOX_TOKEN_SECRET

Check that it starts and that it can see the infrastructure:

set -a && . ./.env && set +a
proxmox-ai            # habla MCP por stdin/stdout; Ctrl-C para salir

Connect it to your MCP client (Claude Desktop, Claude Code, etc.):

{
  "mcpServers": {
    "proxmox": {
      "command": "/opt/proxmox-ai/.venv/bin/proxmox-ai",
      "env": {
        "PROXMOX_HOST": "proxmox.midominio.local",
        "PROXMOX_TOKEN_ID": "ai-agent@pve!mcp",
        "PROXMOX_TOKEN_SECRET": "...",
        "PROXMOX_AI_READ_ONLY": "true",
        "PROXMOX_AI_AUDIT_LOG": "/var/log/proxmox-ai/audit.jsonl"
      }
    }
  }
}

How the security works

Four independent layers. Each one stands on its own:

1. The Proxmox ACL. This is the real frontier. The token is a dedicated user with --privsep 1, never root@pam, and in Phase 1 it only has PVEAuditor. A token that can't delete a VM doesn't delete it even if everything else fails.

2. Capability flags. PROXMOX_AI_READ_ONLY=true blocks any write regardless of the rest of the configuration. Each phase has its own flag, and irreversible operations need an additional one.

3. Two-step confirmation. A write tool called without a confirm_token doesn't touch anything: it returns a plan and a one-time token bound to that exact action. The human sees the plan between the two calls. For irreversible operations you must also send a literal phrase (CONFIRM ROLLBACK SNAPSHOT 105); a "yes" isn't enough.

4. No arbitrary shell. There's no execute_any_command. Commands inside guests go through an argv allowlist, with two blocklists —binaries (rm, dd, bash…) and destructive options— plus shell metacharacter rejection. The option blocklist exists because an apparently read-only binary can have a destructive flag: journalctl -u nginx --vacuum-time=1s deletes archived logs. Arguments are also escaped with shlex.quote, because ssh host cmd always reinterprets the remote shell.

And underneath it all, an append-only JSONL log of every attempt —including rejected ones— with not a single secret in it.

What this doesn't solve: an MCP server cannot distinguish "the human said yes" from "the model decided to go ahead". The two-step confirmation guarantees that nothing irreversible happens as a side effect of a single call, and leaves a trace of everything, but the durable guarantee is the ACL. This is explained without embellishment in docs/modelo-de-seguridad.md.

Tools

Phase 1 — read (active by default, only needs PVEAuditor)

Tools

Phase 1 — read-only (enabled by default, only needs PVEAuditor)

Phase 2 — power (PROXMOX_AI_ENABLE_POWER, priv. VM.PowerMgmt)

pve_guest_power — start, shutdown, reboot, stop. Confirmation required.

Phase 3 — snapshots (PROXMOX_AI_ENABLE_SNAPSHOT, priv. VM.Snapshot)

pve_create_snapshot (level 1) · pve_rollback_snapshot and pve_delete_snapshot (level 2: literal phrase + PROXMOX_AI_ENABLE_DESTRUCTIVE)

Phase 4 — backups (PROXMOX_AI_ENABLE_BACKUP, priv. VM.Backup)

pve_create_backup — level 1. Restore is not implemented on purpose: it's the most destructive operation in Proxmox. See docs/modelo-de-seguridad.md.

Phase 5 — in-guest diagnostics (PROXMOX_AI_ENABLE_GUEST_EXEC)

pve_guest_exec — run a command from the allowlist. Restarting services is phase 1 of guest execution; the environment variable PROXMOX_AI_ENABLE_DESTRUCTIVE doesn't unlock it.

A real example of the two-step confirmation

{
  "mcpServers": {
    "proxmox": {
      "command": "/opt/proxmox-ai/.venv/bin/proxmox-ai",
      "env": {
        "PROXMOX_HOST": "proxmox.midominio.local",
        "PROXMOX_TOKEN_ID": "ai-agent@pve!mcp",
        "PROXMOX_TOKEN_SECRET": "...",
        "PROXMOX_AI_READ_ONLY": "true",
        "PROXMOX_AI_AUDIT_LOG": "/var/log/proxmox-ai/audit.jsonl"
      }
    }
  }
}

The agent proposes a reboot for the guest 105. The policy engine returns a plan and a one-time token:

Usuario:  Reinicia el CT 105.

Agente:   [pve_guest_power vmid=105 operation=reboot]
          → confirmation_required
            "REBOOT CT 105 (web-production) on node pve1 — will request a
             clean reboot via the guest OS."
            nothing_has_changed: true
            confirm_token: "kJ8x...b2"

          Voy a reiniciar el CT 105 (web-production) en el nodo pve1.
          Es un reinicio limpio a través del sistema operativo. ¿Confirmas?

Usuario:  Sí.

Agente:   [pve_guest_power vmid=105 operation=reboot confirm_token="kJ8x...b2"]
          → status: completed

          Reiniciado. La tarea terminó con estado OK.

The human reviews the plan, approves it, and the tool executes exactly and only that actionwards. The token is single-use bind to the exact guest and parameters.

Development

pip install -e ".[dev]"
pytest                    # 229 tests, sin red ni Proxmox real
ruff check src tests

The tests use httpx.MockTransport with a fake cluster (1 node, 2 CTs, 2 storages). You don't need a real Proxmox to develop.

Documentation

• docs/instalacion.md — step-by-step installation

• docs/modelo-de-seguridad.md — threats and limits

• docs/roadmap.md — the 7 phases, with checklist

• docs/especificacion-original.md — the starting document

License

MIT