🖥️ Proxmox MCP Server

Chat with your Proxmox VE cluster. A Model Context Protocol server that turns any MCP‑capable AI — Claude Desktop, Cursor, Continue, Zed — into a natural‑language operator for Proxmox Virtual Environment: nodes, QEMU VMs, LXC containers, storage, tasks and snapshots.

“List my VMs and which are down.” · “How much RAM is web (VMID 101) using?” · “Snapshot db before I upgrade it.” · “Gracefully shut down container 200.”

💻 The built‑in proxmox-mcp-tui terminal dashboard — tabbed views (Guests · Nodes · Storage · Tasks), live CPU/memory/disk gauges, guest OS, search, snapshots and one‑key actions. More screenshots ↓

Designed, built & maintained by SoyRage Agency · https://soyrage.es/

⚡ New here? Install in one command → Quick install. · ☕ Support the project

🐳 Looking for the Docker equivalent? See the sister project docker-mcp-server — same philosophy, for Docker & Compose.

🛡️ NEW — Resilience & Compliance

Stop hoping your backups work. Prove it — with signed evidence auditors accept.

Three new capabilities turn Proxmox MCP Server from “operate the cluster” into “prove the cluster survives a disaster” — each one producing a cryptographically-signed, dated report mapped to ISO 27001 · NIS2 · DORA:

Related MCP server: ProxmoxEmCP

📑 Table of contents

• Quick install (one command)

• What is this?

• Feature overview

• 🛡️ Resilience & Compliance (NEW)

• How it works

• Requirements

• Installation

• The terminal UI (TUI)

• Create a Proxmox API token

• Connecting to your AI client

• Configuration reference

• TLS & self‑signed certificates

• Security model & networking

• Complete tool reference

• Example conversations

• Modular plugin architecture

• Project structure

• Development

• Troubleshooting & FAQ

• Roadmap

• Support the project

• Credits & License

⚡ Quick install (one command)

Just want the terminal dashboard? No Node required. Install the standalone rageprox binary — a Node runtime and the app fused into one file:

Windows (PowerShell):

irm https://raw.githubusercontent.com/soyrageagency/proxmox-mcp-server/main/scripts/install.ps1 | iex

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/soyrageagency/proxmox-mcp-server/main/scripts/install.sh | sh

Then run rageprox (preview with PROXMOX_MCP_DEMO=true rageprox). Re-run the installer any time to update — and the app tells you when a new version ships.

Prefer the MCP-server-for-Claude-Desktop path (with the config wizard)? Use the Node installer below.

Never done this before? It's 3 steps and about 3 minutes. You do not need to touch any config file — a friendly wizard asks you a few questions and sets up everything.

✅ Step 1 — Install the two things you need (once)

• Node.js (click the big green “LTS” button, next‑next‑finish).

• Git.

✅ Step 2 — Run one command

irm https://raw.githubusercontent.com/soyrageagency/proxmox-mcp-server/main/install.ps1 | iex

curl -fsSL https://raw.githubusercontent.com/soyrageagency/proxmox-mcp-server/main/install.sh | bash

✅ Step 3 — Copy‑paste your details when the wizard asks

That's it — the wizard walks you through it and tests the connection for you:

  This wizard sets everything up in under a minute. You'll need:
    1. Your Proxmox web address (the one you log in to).
    2. An API token (safest) — or your Proxmox username + password.

  Proxmox address (e.g. https://192.168.1.10:8006): https://10.0.0.11:8006
  Do you have an API token? (Y/n): y
  Token ID (user@realm!name, e.g. root@pam!mcp): root@pam!mcp
  Token secret (paste the UUID): ••••••••-••••-••••-••••-••••••••••••
  Verify the TLS certificate? (most Proxmox use self-signed → No) (y/N): n
  Read-only mode? (view only — safest) (y/N): n

  Testing the connection…
  ✓ Connected to Proxmox VE (8.2.4)
  ✓ Saved credentials to .env
  ✓ Added the "proxmox" server in your Claude config.

  All set!  →  restart Claude Desktop and ask "List my Proxmox VMs."

Then restart Claude Desktop and say: “List my Proxmox VMs and containers.” 🎉

In the Proxmox web UI: Datacenter → Permissions → API Tokens → Add, pick user root@pam, name it mcp, and copy the secret (shown once). Your token ID is root@pam!mcp. Full details in Create a Proxmox API token. Prefer not to now? The wizard also accepts your username + password.

Run npm run setup from the project folder. The installer backs up and merges your existing Claude config, so other MCP servers are preserved.

Try demo mode — realistic fake data, no host needed.

💙 If this saves you time, please support the project on PayPal and drop a ⭐.

🧭 What is this?

The Model Context Protocol (MCP) is an open standard that lets AI assistants talk to external tools over a well‑defined JSON‑RPC interface. Proxmox MCP Server is an MCP server that speaks that protocol over stdio and exposes your Proxmox VE cluster as a set of safe, richly‑described tools.

Point any MCP‑capable assistant at it and you can operate your virtualization stack in plain language — the model reads each tool's schema, decides which to call against the Proxmox REST API, and reports the results back to you. Built for home‑labbers and sysadmins who'd rather ask than remember qm and pct flags.

🚀 Feature overview

🛠️ How it works

                 ┌──────────────────────────────────────────────┐
   You  ◀──────▶ │  AI assistant (Claude / Cursor / Continue …)  │
                 └───────────────────────┬──────────────────────┘
                              stdio · JSON‑RPC (MCP)
                 ┌───────────────────────▼──────────────────────┐
                 │              Proxmox MCP Server               │
                 │   config → auth → tool call → Proxmox API     │
                 └───────────────────────┬──────────────────────┘
                          HTTPS · /api2/json (token or ticket)
                 ┌───────────────────────▼──────────────────────┐
                 │        Proxmox VE node / cluster (:8006)      │
                 └───────────────────────────────────────────────┘

The server calls the Proxmox VE REST API (https://<host>:8006/api2/json). It resolves each guest's node automatically from /cluster/resources, so you address VMs and containers simply by VMID or name — no need to know which node they live on.

✅ Requirements

📦 Installation

git clone https://github.com/soyrageagency/proxmox-mcp-server.git
cd proxmox-mcp-server
npm install
npm run build

🧪 Try it instantly — demo mode (no Proxmox needed)

Want to evaluate it right now without a cluster? Run in demo mode — the server serves a believable 2‑node lab (VMs, containers, storage, snapshots):

npm run build
PROXMOX_MCP_DEMO=true npm run inspect     # explore every tool in the MCP Inspector

Or point Claude Desktop at it with "PROXMOX_MCP_DEMO": "true" in the env block and ask “List my Proxmox VMs and containers.” You'll get output like:

VMID  KIND  NAME           NODE  STATUS   CPU   MEMORY          UPTIME
100   VM    web            pve   running  3.1%  1.8 GB/4.0 GB   22d 23h
101   VM    db             pve   running  8.7%  6.2 GB/8.0 GB   22d 23h
200   CT    nginx-proxy    pve   running  0.4%  96.0 MB/512 MB  22d 22h
201   CT    grafana        pve   running  1.2%  240 MB/2.0 GB   13d 21h

When you're ready, set PROXMOX_MCP_DEMO=false and add your real host + token.

With a real cluster

npm run inspect     # after setting PROXMOX_HOST + token (see below)

⌨️ The terminal UI (TUI)

Prefer the terminal? Launch proxmox-mcp-tui — a creative, professional, lazydocker‑style dashboard for your cluster that opens with a SoyRage Agency welcome, then drops you into a live, keyboard‑driven view. Hand‑rolled ANSI, zero UI dependencies.

npm run build
npm run tui        # → interactive terminal dashboard
npm run tui:demo   # same, with realistic mock data (no cluster needed)

A warm welcome

Guests — OS, live gauges & one‑key actions

Tabbed views — Nodes · Storage · Tasks

🤖 Give orders to the AI — in plain language

🛡️ Resilience tab — restore-tests, patch runs & DR drills at a glance

Rendered in demo mode · watermarked © SoyRage Agency · soyrage.es

Features

• Tabbed views — 1 Guests · 2 Nodes · 3 Storage · 4 Tasks · 5 Resilience (or Tab to cycle), each with column headers and usage bars.

• 🛡️ Resilience tab — the last verdict for backup verification, patch orchestration and DR drills, with measured RTO/RPO and the signing fingerprint. Press g to run the selected capability and write fresh signed evidence.

• 🤖 AI command bar — press a and type an order in plain English: “restart db”, “shutdown 200”, “which VMs are down?”, “how much RAM is web using?”. The AI proposes the action and asks you to confirm before it runs — questions get an instant answer. Powered by any OpenAI‑compatible endpoint (OpenAI, Ollama, LM Studio…); demo mode simulates it.

• Live — a clock and cluster name in the header, auto‑refreshing every 5 s.

• Search — press / to filter guests by name or VMID.

• Help overlay — press ? for a keyboard cheat‑sheet.

• Safe actions — destructive stop and every AI action ask for a y/n confirmation; read‑only mode hides all action keys.

• Rich details — the selected guest shows its OS (via the QEMU agent), CPU/memory/disk gauges, cores and uptime; press s for its snapshots.

Keys: 1‑5/Tab views · ↑/↓ (or j/k) navigate · / filter · a ask AI · g run resilience · s snapshots · S start · d shutdown · x stop · b reboot · r refresh · ? help · q quit. VMs are cyan, containers magenta.

💡 Enable the AI with PROXMOX_MCP_AI_ENDPOINT (+ _KEY, _MODEL). Works with Ollama locally for free. Without it, the bar still understands common orders via a built‑in rule engine.

🛡️ Resilience & Compliance (NEW)

Anyone can take a backup. The hard part — the part regulators now ask you to prove — is that you can recover. This module adds three capabilities that generate exactly that proof: a cryptographically-signed, dated evidence report (JSON + Markdown + printable HTML) mapped onto ISO 27001, NIS2 and DORA controls.

Every report is signed with an Ed25519 key (auto-generated on first use). An auditor can verify — offline, with only the bundled public key — that the report was produced by your system on the stated date and hasn't been altered since. Zero new dependencies.

Run any capability three ways: from your AI client (the tools below), from the TUI (Resilience tab → press g), or wire it into cron/CI.

✅ 1. Automated backup verification — restore-testing

Almost nobody tests their restores; they find out on the day of the disaster.

verify_backups takes the latest vzdump for each guest, restores it into an ephemeral VM fenced onto an isolated bridge (it can never touch production), boots it, and runs health checks:

• Service up — the guest boots and its agent responds.

• Database responds — e.g. pg_isready accepts connections.

• Key-file checksums — critical files match a recorded baseline (drift is flagged, not rubber-stamped).

Then it destroys the ephemeral guest and signs a report with the measured RTO per guest. Supports ISO 27001 A.8.13 / A.5.29 · NIS2 Art. 21(2)(c) · DORA Art. 12.

verify_backups                    # test the latest backup of every guest
verify_backups { "vmid": 101 }    # just this guest

🔁 2. Patch orchestration with automatic rollback

“I don't touch that server, because if it breaks I don't know how to get back.”

orchestrate_patching removes the fear. For each guest, in dependency order, within an optional maintenance window:

snapshot → apply updates → health check → if it fails, roll back to the snapshot automatically.

You get a report showing exactly what was patched and what was rolled back. Supports ISO 27001 A.8.8 / A.8.32 · NIS2 Art. 21(2)(e) · DORA Art. 9.

orchestrate_patching
orchestrate_patching { "guests": ["web", "db"], "window": "Sat 02:00-05:00" }

🎯 3. Scheduled DR drills

Many companies have their DR plan in a 2019 Word document that nobody has ever executed.

run_dr_drill executes a declarative YAML runbook against an isolated test environment, times every recovery step, measures RTO/RPO and produces the signed drill minutes (“acta”). The engine refuses to run if the runbook's environment looks like production. A ready-to-edit runbook lives in examples/dr-runbook.yaml:

name: Quarterly failover drill
environment: staging          # never "production" — the engine refuses
rpoHours: 24
steps:
  - action: restore
    guest: db
    from: latest
  - action: start
    guest: db
  - action: healthcheck
    guest: db
    check: db
  - action: failover
    guest: web
  - action: teardown

run_dr_drill                                   # built-in sample runbook
run_dr_drill { "path": "examples/dr-runbook.yaml" }
run_dr_drill { "runbook": "name: ...\nsteps: ..." }

Supports ISO 27001 A.5.30 · NIS2 Art. 21(2)(c) · DORA Art. 11 / 24-25.

📄 The evidence

Each run writes to PROXMOX_MCP_RESILIENCE_DIR (default ./resilience-reports/):

list_resilience_reports (available even in read-only mode) shows the most recent verdict per capability.

🔒 Safety. The three run tools are mutating and are hidden in PROXMOX_MCP_READONLY mode (report listing stays available). Backup verification and DR drills operate on ephemeral, isolated guests; patching always snapshots first and rolls back on failure.

⚙️ Configuration

🔑 Create a Proxmox API token

An API token is the safest way to authenticate (no password stored, revocable, scopable).

1. In the Proxmox web UI go to Datacenter → Permissions → API Tokens → Add.

2. Pick a User (e.g. root@pam) and a Token ID (e.g. mcp). Copy the generated secret — it's shown only once.

   • Your PROXMOX_TOKEN_ID is then root@pam!mcp.

3. Give the token permissions. For full control assign the PVEAdmin role at path /; for read‑only use PVEAuditor. (Uncheck Privilege Separation to inherit the user's privileges, or add an ACL for the token.)

4. Put the values in your MCP client config / .env:

   PROXMOX_HOST=https://192.168.1.10:8006
   PROXMOX_TOKEN_ID=root@pam!mcp
   PROXMOX_TOKEN_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Prefer least privilege: pair a PVEAuditor token with PROXMOX_MCP_READONLY=true for a safe, view‑only assistant.

🔌 Connecting to your AI client

Add the server to your MCP client. Example for Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "proxmox": {
      "command": "node",
      "args": ["/absolute/path/to/proxmox-mcp-server/dist/index.js"],
      "env": {
        "PROXMOX_HOST": "https://192.168.1.10:8006",
        "PROXMOX_TOKEN_ID": "root@pam!mcp",
        "PROXMOX_TOKEN_SECRET": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "PROXMOX_VERIFY_TLS": "false",
        "PROXMOX_MCP_READONLY": "false"
      }
    }
  }
}

A ready‑to‑edit copy lives in examples/claude_desktop_config.json. Restart your client and ask: “What Proxmox nodes and VMs do I have?” — the assistant will greet you on behalf of SoyRage Agency and take it from there.

⚙️ Configuration reference

Every setting is an environment variable. A local .env is loaded automatically; a JSON config file (proxmox-mcp.config.json) provides defaults. Precedence (low → high): defaults → config file → .env → environment. See .env.example.

🔒 TLS & self‑signed certificates

Proxmox ships a self‑signed certificate by default, so PROXMOX_VERIFY_TLS=false (the default) is expected for most home‑labs — the connection is still encrypted, just not certificate‑verified. TLS control is per‑request (via undici), so it does not disable verification globally for your process.

Set PROXMOX_VERIFY_TLS=true only when your node presents a certificate your system trusts (e.g. a Let's Encrypt cert, or an internal CA / reverse proxy in front of :8006).

🛡️ Security model & networking

This server can control your infrastructure — treat access like root SSH.

Networking: the Proxmox API listens on :8006. Reach a remote node over a VPN (WireGuard / Tailscale) rather than exposing 8006 to the Internet. The MCP server runs locally beside your AI client and connects out to Proxmox — it opens no inbound ports of its own.

Safety recipes

# View-only assistant (great for demos / dashboards)
PROXMOX_MCP_READONLY=true          # + a PVEAuditor token

# Only let the AI manage two specific guests
PROXMOX_MCP_ALLOWLIST=101,web

# Expose only cluster/guest insight, no storage/tasks
PROXMOX_MCP_PLUGINS=nodes,guests,cluster

🧰 Complete tool reference

Tools marked W change state and are hidden when PROXMOX_MCP_READONLY=true. Guests are addressed by VMID or name.

Identity

Insight (read‑only)

Lifecycle (W)

Management (W)

Backups & provisioning (W)

Snapshots (W)

Resilience & Compliance (W) — details ↑

💬 Example conversations

🧩 Modular plugin architecture

The server is assembled from independent plugins, each owning one capability group; which load is driven entirely by configuration. The about plugin is locked — it carries the SoyRage Agency identity and cannot be disabled.

PROXMOX_MCP_PLUGINS=                                # (env) empty = load all
PROXMOX_MCP_DISABLED_PLUGINS=lifecycle,snapshots    # insight only

Ask the assistant “list the plugins” any time to see what's enabled.

🗂️ Project structure

proxmox-mcp-server/
├── assets/soyrage-banner.svg  # SoyRage Agency identity banner
├── examples/                  # Claude config + config-file examples
├── install.sh / install.ps1   # One-command bootstrap for beginners
├── scripts/install.mjs        # Cross-platform Claude Desktop configurator
├── src/
│   ├── index.ts               # Entry point: banner, attribution guard, wiring
│   ├── branding.ts            # SoyRage identity, ASCII banner, MCP instructions
│   ├── plugins.ts             # Modular plugin catalogue & loader
│   ├── config.ts              # Layered config (defaults → file → .env → env)
│   ├── logger.ts              # stderr-only structured logger
│   ├── proxmox/
│   │   └── client.ts          # Typed Proxmox VE API client (token/ticket, TLS)
│   ├── tools/                 # One module per plugin's tools
│   │   ├── context.ts · about.ts · nodes.ts · guests.ts · cluster.ts
│   │   ├── storage.ts · tasks.ts · snapshots.ts · lifecycle.ts
│   │   ├── management.ts · backups.ts · provisioning.ts · resilience.ts
│   ├── resilience/            # Resilience & Compliance engine
│   │   ├── engine.ts          # Façade: run → sign → persist → summarise
│   │   ├── backup-verifier.ts # Restore-test into an isolated ephemeral VM
│   │   ├── patch-orchestrator.ts  # Snapshot → patch → health → auto-rollback
│   │   ├── dr-drill.ts        # Execute a declarative recovery runbook
│   │   ├── runbook.ts         # Dependency-free YAML runbook parser
│   │   ├── report.ts          # Control mapping + Markdown/HTML rendering
│   │   ├── signing.ts         # Ed25519 evidence signing (node:crypto)
│   │   └── types.ts · util.ts
│   └── utils/                 # format.ts (tables/units) · result.ts (MCP helpers)
├── examples/dr-runbook.yaml   # Ready-to-edit DR drill runbook
├── .env.example · LICENSE · NOTICE · README.md

🧪 Development

npm run dev        # hot-reload with tsx
npm run typecheck  # strict type check, no emit
npm run build      # compile to dist/
npm run start      # run the built server
npm run inspect    # launch the MCP Inspector
npm run setup      # build + configure Claude Desktop

Design notes: stdout is reserved for the JSON‑RPC stream (logs → stderr); the Proxmox client resolves guest → node automatically; failing tool calls return a clean isError result instead of crashing the connection; TLS control is per‑request via undici.

🩺 Troubleshooting & FAQ

Check PROXMOX_HOST (include https:// and :8006), that the node is reachable (VPN?), and your token/credentials. With a self‑signed cert keep PROXMOX_VERIFY_TLS=false. The server keeps running so tool calls return a friendly error in your chat client.

The token/user lacks privileges for that path. Assign an appropriate role (PVEAuditor for read, PVEAdmin/PVEVMAdmin for control) at path / or on the specific VM, and make sure the token isn't limited by Privilege Separation without an ACL.

You're in read‑only mode (PROXMOX_MCP_READONLY=true) or the lifecycle plugin is disabled. Adjust and restart your MCP client.

No. The server talks only to your Proxmox API and your MCP client over local stdio. It makes no other outbound calls.

🗺️ Roadmap

• Nodes, guests, lifecycle, snapshots, storage, tasks, cluster

• Guest OS detection (QEMU agent) · suspend/resume

• Migrate, clone, resize, backup (vzdump), delete guests

• Backups: list & restore archives · Provisioning: create VMs/CTs from templates & ISOs

• Guided setup wizard · API‑token & ticket auth · read‑only & allowlist · modular plugins

• One‑command installer · demo mode · terminal UI (TUI) · CI

• Resilience & Compliance: signed backup verification · patch orchestration with auto‑rollback · DR drills (ISO 27001 / NIS2 / DORA)

• Scheduled resilience runs (cron) & e‑mail/Slack delivery of evidence

• Cloud‑init provisioning presets

• Published npm package for one‑line npx usage

🧰 More from the SoyRage self‑hosting suite

Proxmox MCP Server is part of a family of open‑source infrastructure tools built with the same care — same design language, same safety‑first defaults, same "chat with your infra" philosophy:

💙 Support the project

Proxmox MCP Server is built and maintained in the open by SoyRage Agency. If it's useful, please consider supporting continued development — it funds new features and keeps the project free.

paypal.me/soyrageagency · a ⭐ on the repo also helps a lot!

Other ways to help: share it on r/selfhosted or r/Proxmox, report issues, open PRs, or hire SoyRage Agency for custom DevOps + AI tooling.

🖋️ Credits & License

Designed, built and maintained by SoyRage Agency — https://soyrage.es/

Released under the SoyRage Attribution License (see LICENSE and NOTICE). You may use, modify and self‑host it — as long as the credit to SoyRage Agency stays visible: the source headers, the package.json author field, and the runtime identity (ASCII banner, about tool, MCP instructions) must remain intact.

ℹ️ On attribution: software that runs on your machine can always be modified — this is not DRM. The attribution is the default everywhere so removing it is a deliberate act, and the license makes that act a violation. For white‑labelling or a commercial license, reach out via soyrage.es.

© 2026 SoyRage Agency — https://soyrage.es/ · Made with care in Valencia, Spain.