🖥️ 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.”

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.

📑 Table of contents

• Quick install (one command)

• What is this?

• Feature overview

• 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

Related MCP server: Proxmox MCP Server

⚡ Quick install (one command)

New to this? The installer clones the project, builds it, and runs a guided setup wizard — you just paste your Proxmox address and API token, it tests the connection, and writes everything (.env + Claude Desktop config) for you. You only need Git and Node.js ≥ 18.

Windows (PowerShell):

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

macOS / Linux:

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

The wizard asks a few simple questions and looks like this:

  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."

Already cloned the repo? Just run npm run setup. Don't have a token yet? See Create a Proxmox API token (2 minutes). Want to try it with no cluster at all? Jump to demo mode.

The installer backs up and merges your existing config, so other MCP servers are preserved.

💙 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, lazydocker‑style dashboard for your cluster that opens with a SoyRage Agency welcome, then drops you into a live, keyboard‑driven view of your VMs and containers. 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

Live dashboard — guests, OS, gauges & one‑key actions

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

Keys: ↑/↓ (or j/k) navigate · s snapshots · S start · d shutdown · x stop · b reboot · r refresh · q quit. VMs are cyan, containers magenta; the details pane shows the guest OS, CPU/memory/disk gauges and uptime. Read‑only mode hides the action keys.

🔑 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)

Snapshots (W)

💬 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
│   └── utils/                 # format.ts (tables/units) · result.ts (MCP helpers)
├── .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

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

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

• Backup restore & scheduled backup jobs

• VM/CT create from ISO/template

• Published npm package for one‑line npx usage

💙 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.