Proxmox MCP Server
The Proxmox MCP Server lets AI assistants manage and monitor Proxmox VE clusters using natural language, providing comprehensive control over your virtualized environment.
Cluster & Node Insight
List cluster nodes with status, CPU load, and memory usage
Get detailed node status (CPU/memory/swap, uptime, kernel/PVE versions)
View cluster membership, quorum status, and consolidated cluster resources
Guest Inventory & Details
List all VMs and LXC containers with live stats, filterable by type or running-only
Get live runtime status, full configuration, and guest OS info (name, version, IPs via QEMU agent)
Lifecycle Management
Start, gracefully shut down, hard stop, reboot, suspend/resume guests
Migrate guests between nodes (with live/online migration support)
Clone VMs/containers (e.g., from templates, full or linked clone)
Resize CPU cores and memory for any guest
Permanently delete a guest and its disks (guarded by VMID confirmation)
Snapshots
List, create (optionally with RAM state), rollback to, and delete snapshots
Backups & Restore
Create vzdump backups, list available backup archives, and restore them to a specific VMID
Provisioning
List available container templates and ISOs
Create new LXC containers or QEMU VMs from templates or ISOs
Storage & Tasks
List storages on a node with type, content, and usage statistics
View recent task history (VM starts, backups, migrations, snapshots, etc.)
Safety & Security
Global read-only mode to prevent state changes
Guest allowlist to restrict which guests the AI may touch
Secure authentication via scoped Proxmox API tokens; TLS verification toggle
Modular Plugin Design
Capabilities are organized into toggleable plugins; enable/disable groups as needed
Identity plugin (server info, list plugins) is always available
Terminal UI (TUI)
Interactive keyboard-driven dashboard with live gauges, tabbed views (Guests, Nodes, Storage, Tasks), an AI command bar, search, and one-key actions
Demo Mode
Test with realistic fake data without needing a real Proxmox cluster
Provides tools for managing Proxmox VE clusters, including nodes, QEMU VMs, LXC containers, storage, snapshots, tasks, and guest lifecycle operations via natural language.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Proxmox MCP Server List my VMs and their status"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
π₯οΈ 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.
π³ Looking for the Docker equivalent? See the sister project docker-mcp-server β same philosophy, for Docker & Compose.
β¨ New in this release
π | Run it on the cluster, not on your laptop | MCP normally means one server process per client, on the client's machine β backwards when the thing you are managing is the server. Set |
π©Ί | "Is anything wrong?" in one call |
|
π¬ | Workflows your client offers you | MCP prompts β audit my cluster, plan a maintenance window, explain this guest, free up space. You no longer have to know which tool to ask for. β Guided workflows |
See the roadmap for what comes next.
Related MCP server: ProxmoxEmCP
π‘οΈ 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:
Capability | What it does | |
β | Restores your latest | |
π | Snapshot β apply updates β health check β if it fails, roll back automatically. In dependency order, within a maintenance window. Kills the βI don't touch that server because I can't undo itβ fear. | |
π― | Executes a declarative YAML runbook against an isolated test env and generates the drill minutes (βactaβ). No more DR plan rotting in a 2019 Word doc nobody ever ran. |
π Table of contents
β‘ Quick install (one command)
Already use an MCP client? Point it at the published package β nothing to clone or build:
"proxmox": { "command": "npx", "args": ["-y", "@soyrageagency/proxmox-mcp"], "env": { "PROXMOX_HOST": "https://192.168.1.10:8006", "PROXMOX_TOKEN_ID": "root@pam!mcp", "PROXMOX_TOKEN_SECRET": "β¦" } }Or try the terminal dashboard straight away:
npx -y -p @soyrageagency/proxmox-mcp proxmox-mcp-tui
Just want the terminal dashboard? No Node required. Install the standalone
rageproxbinary β 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 | iexmacOS / Linux:
curl -fsSL https://raw.githubusercontent.com/soyrageagency/proxmox-mcp-server/main/scripts/install.sh | shThen run
rageprox(preview withPROXMOX_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)
β Step 2 β Run one command
irm https://raw.githubusercontent.com/soyrageagency/proxmox-mcp-server/main/install.ps1 | iexcurl -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.
π§ 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
Area | Capabilities |
π§ Cluster | List nodes with load, node status, cluster quorum/membership, and a consolidated |
π₯οΈ Guests | List QEMU VMs and LXC containers (filter by kind / running), live status, full config, and guest OS (via the QEMU agent β name, version, IPs). |
βοΈ Lifecycle | Start Β· graceful shutdown Β· hard stop Β· reboot Β· suspend/resume β for VMs and containers. |
π Management | Migrate to another node Β· clone (from templates) Β· resize CPU/RAM Β· delete. |
π¦ Backups | Backup (vzdump) Β· list archives Β· restore into a VMID. |
π§± Provisioning | List templates/ISOs Β· create LXC containers and QEMU VMs. |
πΈ Snapshots | List, create (optionally with RAM), rollback and delete snapshots. |
π‘οΈ Resilience & Compliance | Restore-test backups in an isolated VM Β· patch with automatic rollback Β· run DR drills β each producing a signed ISO 27001 / NIS2 / DORA evidence report. See β |
πΎ Storage | List storages per node with type, content and usage. |
π§Ύ Tasks | Recent task log per node (backups, migrations, actionsβ¦). |
β¨οΈ Terminal UI | A creative, lazydockerβstyle TUI ( |
π‘οΈ Safety | Global readβonly mode Β· guest allowlist (by VMID or name) Β· TLS verification control. |
π Auth | API token (recommended) or username/password ticket auth. |
π§© Modular | Every capability is a toggleable plugin β expose exactly the surface you want. |
π§± Engineering | 100% TypeScript, strict mode Β· tiny dependency surface Β· stderrβonly logging. |
π οΈ 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
Requirement | Notes |
Node.js β₯ 18 | ES modules + global |
A Proxmox VE 7/8 node or cluster | Reachable on its API port ( |
An API token (recommended) | Or a user/password. See Create a Proxmox API token. |
An MCP client | Claude Desktop, Cursor, Continue, Zed, or the MCP Inspector. |
π¦ 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 InspectorOr 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 21hWhen 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 β
1Guests Β·2Nodes Β·3Storage Β·4Tasks Β·5Resilience (orTabto 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
gto run the selected capability and write fresh signed evidence.π€ AI command bar β press
aand 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
stopand every AI action ask for ay/nconfirmation; 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
sfor 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_isreadyaccepts 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: teardownrun_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/):
File | For |
| A branded report that prints straight to PDF for an auditor (shown above). |
| A diff-able Markdown report that lives in git. |
| The machine-readable record, including the signature block. |
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_READONLYmode (report listing stays available). Backup verification and DR drills operate on ephemeral, isolated guests; patching always snapshots first and rolls back on failure.
βοΈ Configuration
Variable | Default | Purpose |
|
| Where signed evidence is written. |
| (auto) | Path to the Ed25519 signing key (generated if absent). |
|
| First VMID of the ephemeral restore range. |
|
| Isolated bridge ephemeral guests are fenced onto. |
| (anytime) | Default patching window, e.g. |
π Create a Proxmox API token
An API token is the safest way to authenticate (no password stored, revocable, scopable).
In the Proxmox web UI go to Datacenter β Permissions β API Tokens β Add.
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_IDis thenroot@pam!mcp.
Give the token permissions. For full control assign the
PVEAdminrole at path/; for readβonly usePVEAuditor. (Uncheck Privilege Separation to inherit the user's privileges, or add an ACL for the token.)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
PVEAuditortoken withPROXMOX_MCP_READONLY=truefor 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": "npx",
"args": ["-y", "@soyrageagency/proxmox-mcp"],
"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"
}
}
}
}No install step needed: npx fetches the package on first run and keeps it up to date. 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?β
π Run it over the network (HTTP)
By default an MCP server talks over stdio: your AI client starts a copy of it as a child process, on your machine. That is fine for a laptop tool and awkward for a homelab, where the cluster you want to manage is a different machine entirely β and where you probably want your desktop, your laptop and your phone all talking to the same thing.
Set one variable and it serves Streamable HTTP instead:
PROXMOX_MCP_HTTP=true PROXMOX_MCP_HTTP_TOKEN="$(openssl rand -hex 32)" PROXMOX_HOST=https://192.168.1.10:8006 PROXMOX_TOKEN_ID='root@pam!mcp' PROXMOX_TOKEN_SECRET=β¦ npx -y @soyrageagency/proxmox-mcpThen point any MCP client at it:
{
"mcpServers": {
"proxmox": {
"type": "http",
"url": "http://10.0.0.5:8619/mcp",
"headers": { "Authorization": "Bearer <the token you generated>" }
}
}
}Variable | Default | What it does |
|
| Serve over HTTP instead of stdio. |
|
| Interface to bind. Use |
|
| TCP port. |
|
| Endpoint path. |
| (none) | Bearer token required on every request. Set this. |
| derived |
|
| (none) |
|
Read this before you expose it. Anyone who can reach the port can control
your cluster. It binds loopback by default and warns loudly if you start it
without a token. Put it behind your VPN β this is not a service to publish to
the Internet, and combining it with PROXMOX_MCP_READONLY=true is a good idea
for anything you do not fully trust.
There is also GET /health, which needs no token, for LXC and container
healthchecks.
π©Ί Diagnostics
Three read-only tools aimed at the questions you actually ask, rather than at the API surface:
cluster_health β one call that answers is anything wrong? It checks
quorum, per-node CPU and memory pressure, storage headroom, guests that are not
running, how stale the newest backup is, and which guests have no backup at
all. It reports findings ranked by severity, not a data dump:
MOSTLY HEALTHY β 2 warning(s), nothing critical.
AREA DETAIL
- ------- -----------------------------------------------------------------
! guests 2 of 7 guest(s) not running: 102 windows-rdp, 203 backup-runner.
! backups 4 guest(s) have no backup at all: 102, 200, 202, 203.
β quorum Cluster "soyrage-lab" is quorate (2 nodes).
β nodes All 2 node(s) online.
β storage All 3 storage(s) below 85.0%.find_idle_guests β guests with long uptime and near-zero CPU, sorted by
the memory they are holding. It also says out loud that idle-by-design services
exist, so the assistant does not cheerfully suggest shutting down your DNS
resolver.
find_orphaned_disks β disk images whose owning VMID has no guest. Deleting
a VM does not always remove every volume, and the leftovers are invisible in the
web UI. On a lab that has been running a while this routinely finds tens of GB.
All three are read-only, so they stay available with PROXMOX_MCP_READONLY=true,
and all three work in demo mode.
π¬ Guided workflows (prompts & resources)
Tools only answer a question you already knew how to ask. MCP prompts are the other half: your client lists them, so the workflow is discoverable without knowing which of the 39 tools to reach for or in what order.
Prompt | What it does |
audit-cluster | Full read-only sweep β health, waste, idle guests, backup coverage β ending in a prioritised list of what to do. Narrow it with |
plan-maintenance | Works out the safe order to reboot or patch, what to snapshot first, and what breaks while each guest is down. |
explain-guest | Everything about one VM or container in plain language, including whether it is actually protected. |
free-up-space | Finds reclaimable space and ranks it by space returned Γ· risk, with the command for each. |
Each prompt also tells the assistant what a good answer looks like: verdict first, findings ranked, no padding, and an explicit instruction not to change anything.
Resources expose the cluster as attachable context, so the model can be handed the current picture instead of spending three tool calls rebuilding it:
proxmox://cluster/overviewβ nodes, guests and storage in one snapshot.proxmox://server/capabilitiesβ which plugins are loaded, whether the server is read-only, and what the allowlist permits.
βοΈ 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.
Variable | Default | Description |
| β | API base URL, e.g. |
| β | API token id |
| β | API token secret (UUID). |
| β |
|
| β | Password for ticket auth. |
|
| Verify the node's TLS certificate. |
|
| Hide all stateβchanging tools. |
|
| Serve fabricated demo data (no real host needed). |
| β | Commaβseparated VMIDs/names the AI may touch (empty = all). |
| β | Load only these plugins (empty = all). |
| β | Disable these plugins. |
|
|
|
| β | OpenAIβcompatible base URL for the TUI's AI copilot (empty = ruleβbased). |
| β | Bearer key for the AI endpoint. |
|
| Model name for the AI endpoint. |
|
| Path to the optional JSON config file. |
π 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.
Control | What it does |
Readβonly mode ( | Hides every lifecycle/snapshotβmutating tool. Pair with a |
Guest allowlist ( | Restricts all guest tools to matching VMIDs/names; anything else returns a clear error. |
Scoped API token | Grant the token only the privileges it needs; revoke instantly from the UI. |
Least privilege |
|
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
Tool | Description |
| Version, credits and the welcome banner. |
| The modular plugins and whether each is enabled. |
Insight (readβonly)
Tool | Parameters | Description |
| β | Cluster nodes with status, CPU and memory. |
|
| Detailed status of one node. |
|
| All VMs & containers with live stats. |
|
| Live status of one VM/container. |
|
| Full configuration of one guest. |
|
| The guest's operating system (agent name/version + IPs). |
|
| Storages on a node with usage. |
|
| Recent tasks on a node. |
| β | Cluster membership & quorum. |
|
| Consolidated nodes/guests/storage view. |
|
| Snapshots of a VM/container. |
|
| vzdump backup archives with VMID, size, age. |
|
| Container templates (vztmpl) and install ISOs. |
| β | Recent signed resilience evidence (verify / patch / DR). |
Lifecycle (W)
Tool | Parameters | Description |
|
| Power on a VM/container. |
|
| Graceful ACPI/OS shutdown (preferred). |
|
| Hard stop (powerβcord). Destructive β confirm first. |
|
| Graceful reboot. |
|
| Pause a VM in RAM (or hibernate to disk). |
|
| Resume a suspended VM. |
Management (W)
Tool | Parameters | Description |
|
| Move a guest to another node (live if running). |
|
| Clone a VM/CT (e.g. from a template). |
|
| Quickly change CPU cores / RAM (MB). |
|
| Create a vzdump backup to a storage. |
|
| Destroy a guest (guarded: |
Backups & provisioning (W)
Tool | Parameters | Description |
|
| Restore a vzdump archive into a VMID. |
|
| Create an LXC container from a template. |
|
| Create a QEMU VM (with a disk + optional install ISO). |
Snapshots (W)
Tool | Parameters | Description |
|
| Take a snapshot (optionally with VM RAM). |
|
| Revert to a snapshot (destructive). |
|
| Remove a snapshot. |
Resilience & Compliance (W) β details β
Tool | Parameters | Description |
|
| Restore-test the latest backup(s) in an isolated ephemeral VM; sign the report. |
|
| Snapshot β patch β health-check β auto-rollback on failure; sign the report. |
|
| Execute a declarative YAML DR runbook; sign the drill minutes. |
π¬ Example conversations
You say⦠| The assistant calls⦠|
βShow me all my VMs and containers.β |
|
βWhich containers are running?β |
|
βIs node pve healthy?β |
|
βHow is VMID 101 doing?β |
|
βSnapshot db before the upgrade.β |
|
βGracefully shut down container 200.β |
|
βHow full is storage on pve?β |
|
βWhat happened on pve recently?β |
|
βWho built this?β |
|
π§© 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.
Plugin | Category | Type | Tools |
| identity | read |
|
| nodes | read |
|
| guests | read |
|
| storage | read |
|
| tasks | read |
|
| cluster | read |
|
| snapshots | read/write |
|
| lifecycle | write |
|
| management | write |
|
| backups | read/write |
|
| provisioning | read/write |
|
| resilience | read/write |
|
PROXMOX_MCP_PLUGINS= # (env) empty = load all
PROXMOX_MCP_DISABLED_PLUGINS=lifecycle,snapshots # insight onlyAsk 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, 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 Β· 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 DesktopDesign 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
The full roadmap β what is shipped, what is next, and what is deliberately not planned β lives in ROADMAP.md.
The short version: one-command install into an LXC on any Proxmox host, then finer-grained permissions than the current read-only/read-write switch. Metrics history and multi-cluster are further out because they need real design first.
Explicitly not planned: replacing the Proxmox web UI, autonomous action without confirmation, and telemetry of any kind.
π§° 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:
Project | What it does |
π§ Proxmox MCP Server | (you are here) Chat with your Proxmox VE cluster β nodes, VMs & LXC, snapshots and full guest CRUD, plus a tabbed terminal dashboard with an AI command bar. |
π³ Docker MCP Server | Chat with your Docker host β containers, logs, Compose, a live web panel and a TUI with an AI copilot. |
Leaving vSphere after the Broadcom price hikes? Inventory vCenter, score compatibility, estimate cost & time, plan disk conversion and export a professional PDF assessment. | |
πΊοΈ NetAtlas | Living infrastructure documentation β agentless discovery that auto-generates a network diagram, inventory, VLAN & service-dependency maps, and tells you what changed since last time. |
π‘οΈ MailAegis | Corporate email threat analyzer β VirusTotal, ClamAV and an in-house phishing/BEC engine, inside a mail client. |
π Support the project
Proxmox MCP Server is free and MIT licensed. If it saves you time, you can support development on PayPal β a β on the repo helps just as much.
ποΈ Credits & License
Designed, built and maintained by SoyRage Agency β https://soyrage.es/
Released under the MIT License β use it, modify it, self-host it, ship it commercially.
If you build something on top of it, a link back to soyrage.es is appreciated but never required.
Β© 2026 SoyRage Agency β https://soyrage.es/ Β· Made with care in Valencia, Spain.
Available Tools
27 toolsaboutAbout this serverA
Show who built this Proxmox MCP Server and how it is licensed. Call this to greet the user with the SoyRage Agency welcome banner.
Inputs: no named parameters.
backup_guestBackup guest (vzdump)A
Create a backup of a VM or container to a storage using vzdump. mode snapshot (default, no downtime), suspend, or stop.
Inputs: guest (required), storage (required), mode, compress.
clone_guestClone guestA
Clone a VM or container into a new one. Great for deploying from a template. full makes an independent full clone (vs. a linked clone).
Inputs: guest (required), newid (required), full, name, +1 more.
cluster_resourcesCluster resourcesA
A single consolidated view of the cluster's resources β nodes, VMs, containers and storage β with status and utilisation. Filter by type.
Inputs: type.
cluster_statusCluster statusA
Report cluster membership and quorum: each node's online state and whether the cluster is quorate. On a single node it reports standalone.
Inputs: no named parameters.
create_snapshotCreate snapshotA
Take a snapshot of a VM or container. Optionally include the VM's RAM (vmstate) so it can be resumed exactly.
Inputs: name (required), guest (required), withRam, description.
delete_guestDelete guestA
PERMANENTLY destroy a VM or container and its disks. IRREVERSIBLE. You must pass confirm equal to the guest's VMID to proceed.
Inputs: guest (required), confirm (required), purge.
delete_snapshotDelete snapshotB
Remove a snapshot from a VM or container.
Inputs: name (required), guest (required).
guest_configGuest configA
Return the full configuration of a VM or container (cores, memory, disks, network interfaces, boot order, β¦).
Inputs: guest (required).
guest_osinfoGuest OS infoA
What operating system does a guest run? Returns the configured OS type and, for running QEMU VMs with the guest agent, the detected OS name/version and IP addresses. Answers 'what OS is VMID 101?'.
Inputs: guest (required).
guest_statusGuest statusA
Live runtime status of a single VM or container: run state, CPU %, memory, disk, uptime and (for VMs) QEMU guest-agent availability.
Inputs: guest (required).
list_guestsList VMs & containersA
List all QEMU virtual machines and LXC containers across the cluster with their VMID, type, node, status and live CPU/memory. Optionally filter by kind ('qemu' or 'lxc') or only running guests.
Inputs: kind, runningOnly.
list_nodesList nodesA
List the Proxmox VE cluster nodes with their online status, CPU load and memory usage. The best starting point to understand the cluster.
Inputs: no named parameters.
list_pluginsList pluginsA
Show the modular capability plugins this server exposes and whether each is currently enabled.
Inputs: no named parameters.
list_snapshotsList snapshotsA
List the snapshots of a VM or container, including their name, parent and description. The synthetic 'current' entry marks the live state.
Inputs: guest (required).
list_storageList storageA
List the storages configured on a node β type (dir/lvm/zfs/ceph/nfsβ¦), what content they hold, and how full they are.
Inputs: node (required).
list_tasksList recent tasksA
List the most recent tasks on a node (VM starts, backups, migrations, snapshotsβ¦) with their type, status and who ran them. Great for answering 'what happened on this node lately?'.
Inputs: node (required), limit.
migrate_guestMigrate guestA
Migrate a VM or container to another cluster node. Running guests are migrated online (live) when possible.
Inputs: guest (required), target (required), online.
node_statusNode statusA
Detailed status for a single node: CPU/memory/swap, load average, uptime, kernel and PVE versions.
Inputs: node (required).
reboot_guestReboot guestA
Gracefully reboot a running VM or container.
Inputs: guest (required).
resume_guestResume guestB
Resume a suspended/paused VM.
Inputs: guest (required).
rollback_snapshotRollback snapshotA
Revert a VM or container to a snapshot. This is DESTRUCTIVE β any changes made since the snapshot are lost. Confirm with the user first.
Inputs: name (required), guest (required).
set_guest_resourcesSet guest resourcesB
Quickly change a guest's CPU cores and/or memory. For VMs, memory is in MB. Some changes need a reboot to take effect.
Inputs: guest (required), cores, memory.
shutdown_guestShutdown guest (graceful)A
Gracefully shut down a VM or container via ACPI/guest OS. This is the safe way to power off β prefer it over stop_guest.
Inputs: guest (required), timeout.
start_guestStart guestA
Power on a VM or container. No-op if it is already running.
Inputs: guest (required).
stop_guestStop guest (hard)A
Immediately stop a VM or container β equivalent to pulling the power cord. May cause data loss; prefer shutdown_guest. Confirm first.
Inputs: guest (required).
suspend_guestSuspend guestA
Suspend (pause) a running VM β freezes it in RAM so it can be resumed instantly. Set toDisk to hibernate to disk instead.
Inputs: guest (required), toDisk.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 27 tools
Each tool targets a distinct action or resource. For example, guest_status, guest_config, and guest_osinfo are clearly separate. Even closely related tools like cluster_resources and cluster_status have well-defined, non-overlapping purposes.
Most tools follow a verb_noun pattern (e.g., backup_guest, list_nodes), but a few like guest_config, cluster_status, and about deviate slightly. Overall, naming is clear and predictable.
27 tools cover a wide range of Proxmox management tasks (cluster, nodes, guests, storage, backups, snapshots) without being excessive. The count feels well-scoped for the server's purpose.
Core workflows are addressed, but there are gaps like no direct 'create guest' (only clone), no tool to update full guest config, no restore from backup, and limited node maintenance actions. These missing operations could cause agent failures in some scenarios.
Maintenance
Related MCP Connectors
Manage Vozora VPS servers, SSH keys, firewalls, DNS and usage from an AI agent.
Manage VeriTeknik servers, DNS, backups and support tickets from your AI assistant.
Manage Rackspace Spot Kubernetes Cloudspaces, node pools, and VMs from your AI assistant.
Manage American Cloud VMs, Kubernetes, databases, storage, networks and DNS from your AI assistant.
Related MCP Servers
- AlicenseCqualityDmaintenanceEnables management of Proxmox VE infrastructure through natural language, providing 120+ tools to control virtual machines, containers, storage, cluster resources, users, and network configurations via the Proxmox API.10022 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage Proxmox VE infrastructure, including VMs, containers, storage, and cluster operations via natural language.MIT
- AlicenseCqualityDmaintenanceEnables management of Proxmox VE environments, including VMs, containers, storage, and cluster operations through natural language.7653 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to monitor and manage Proxmox VE infrastructure, including nodes, VMs, containers, storage, backups, and networking, via natural language.1MIT