Skip to content
Back to search

proxmox-mcp-server

MCP server for managing Proxmox Virtual Environment VMs, containers, storage, and cluster resources

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/ry-ops/proxmox-mcp-server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/ry-ops/proxmox-mcp-server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ry-ops--proxmox-mcp-server/badge.svg)](/listings/ry-ops--proxmox-mcp-server)

HTML

<a href="/listings/ry-ops--proxmox-mcp-server"><img src="/api/listings/ry-ops--proxmox-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

You need **Python 3.10+** with [`uv`](https://github.com/astral-sh/uv), or Docker, and **Proxmox VE 6.0 or later**.

**1. Make an API token.** In the Proxmox UI, go to **Datacenter → Permissions → API Tokens → Add**. For full access, uncheck *Privilege Separation* so the token inherits your user's permissions. Copy the secret; you won't see it again. The full token ID looks like `root@pam!automation`.

**2. Run the server** with one of these:

<details open> <summary><b>uv, from a clone</b></summary>

curl -LsSf https://astral.sh/uv/install.sh | sh     # if you don't have uv
git clone https://github.com/ry-ops/proxmox-mcp-server && cd proxmox-mcp-server
./setup.sh                                          # or: uv sync

export PROXMOX_HOST="192.168.1.100"
export PROXMOX_USER="root@pam"
export PROXMOX_TOKEN_NAME="automation"
export PROXMOX_TOKEN_VALUE="your-token-here"
./test-connection.sh                                # checks connection, auth and permissions

A `.env` file in the project directory is loaded automatically; see [`.env.example`](.env.example). </details>

<details> <summary><b>Docker</b></summary>

A multi-arch image is published to GitHub Container Registry on every push to `main` and for each release tag:

docker pull ghcr.io/ry-ops/proxmox-mcp-server:latest   # or a version tag, e.g. :2.3.0
docker run -i --rm --env-file .env ghcr.io/ry-ops/proxmox-mcp-server:latest

MCP clients talk over stdio, so run the container interactively (`-i`). `docker-compose.yaml` does the same using your `.env`. </details>

**3. Connect your MCP client.** For Claude Desktop, edit `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, or `%APPDATA%/Claude/claude_desktop_config.json` on Windows:

<details open> <summary><b>uv + API token (recommended)</b></summary>

{
  "mcpServers": {
    "proxmox": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/proxmox-mcp-server", "run", "proxmox-mcp-server"],
      "env": {
        "PROXMOX_HOST": "192.168.1.100",
        "PROXMOX_USER": "root@pam",
        "PROXMOX_TOKEN_NAME": "automation",
        "PROXMOX_TOKEN_VALUE": "your-token-value-here"
      }
    }
  }
}

Use the **absolute** path to your clone. </details>

<details> <summary><b>uv + password</b></summary>

{
  "mcpServers": {
    "proxmox": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/proxmox-mcp-server", "run", "proxmox-mcp-server"],
      "env": {
        "PROXMOX_HOST": "192.168.1.100",
        "PROXMOX_USER": "root@pam",
        "PROXMOX_PASSWORD": "your-password-here"
      }
    }
  }
}

</details>

<details> <summary><b>Docker</b></summary>

{
  "mcpServers": {
    "proxmox": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-e", "PROXMOX_HOST", "-e", "PROXMOX_USER", "-e", "PROXMOX_TOKEN_NAME", "-e", "PROXMOX_TOKEN_VALUE",
        "ghcr.io/ry-ops/proxmox-mcp-server:latest"],
      "env": {
        "PROXMOX_HOST": "192.168.1.100",
        "PROXMOX_USER": "root@pam",
        "PROXMOX_TOKEN_NAME": "automation",
        "PROXMOX_TOKEN_VALUE": "your-token-value-here"
      }
    }
  }
}

</details>

**4. Restart your client completely** (quit it, don't just close the window), and ask it to list your VMs. More detail in [QUICKSTART.md](QUICKSTART.md) and [SETUP.md](SETUP.md).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 760 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="docs/hero.svg" width="100%" alt="You ask your assistant to clone VM 9000 to web-02 and start it; clone_vm and start_vm flow over MCP, by stdio or HTTP, through proxmox-mcp-server to the Proxmox cluster, and the new VM lights up on pve2.">
  3. </p>
  4. <p align="center">
  5. <a href="https://github.com/ry-ops/proxmox-mcp-server/releases"><img src="https://img.shields.io/github/v/release/ry-ops/proxmox-mcp-server?color=ff8a1f&label=release" alt="Release"></a>
  6. <img src="https://img.shields.io/badge/tools-346-ff8a1f" alt="346 tools">
  7. <a href="#pdm"><img src="https://img.shields.io/badge/Datacenter_Manager-89_tools-3ddc84" alt="Proxmox Datacenter Manager: 89 tools"></a>
  8. <a href="#deploy"><img src="https://img.shields.io/badge/deploy_by_asking-Ubuntu_%C2%B7_Kali_%C2%B7_Win11_%C2%B7_PDM-b58cff" alt="Deploy Ubuntu, Kali, Windows 11 and PDM by asking"></a>
  9. <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10+-3ec7ff" alt="Python 3.10+"></a>
  10. <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-2.x-b58cff" alt="MCP SDK 2.x"></a>
  11. <a href="https://github.com/ry-ops/proxmox-mcp-server/pkgs/container/proxmox-mcp-server"><img src="https://img.shields.io/badge/docker-ghcr.io-3ddc84" alt="Docker image on ghcr.io"></a>
  12. <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-ffb02e" alt="MIT"></a>
  13. </p>
  14. <p align="center"><b>Talk to your Proxmox cluster.</b> A Model Context Protocol server that gives Claude, or any MCP client, the <b>whole Proxmox VE API</b>: 346 tools across VMs, containers, storage, clustering, Ceph, SDN and more. Add <b>Proxmox Datacenter Manager</b> for 89 more that reach every cluster and Backup Server it manages, and <b>ask for a machine by name</b>: Ubuntu, Kali, Windows 11 or a Datacenter Manager.</p>
  15. <p align="center">
  16. <a href="#talk">Talk to it</a> ·
  17. <a href="#how">How it works</a> ·
  18. <a href="#tools">346 tools</a> ·
  19. <a href="#prompts">Prompts</a> ·
  20. <a href="#quick-start">Quick start</a> ·
  21. <a href="#clusters">Clusters</a> ·
  22. <a href="#deploy">Deploy by asking</a> ·
  23. <a href="#pdm">Datacenter Manager</a> ·
  24. <a href="#toolsets">Toolsets</a> ·
  25. <a href="#http">HTTP</a> ·
  26. <a href="#read-only">Safety</a> ·
  27. <a href="#wait">Waiting</a> ·
  28. <a href="#a2a">A2A</a> ·
  29. <a href="#troubleshooting">Troubleshooting</a>
  30. </p>
  31. ---
  32. ## ✨ Highlights
  33. - 🧑‍🚀 **Ask for a machine, get a running one.** "Spin up a Kali VM" runs `deploy_kali_vm`: official image, checksum checked, installed unattended, address reported. Ubuntu, Windows 11 (TPM, Secure Boot, VirtIO) and Datacenter Manager work the same way. [More](#deploy)
  34. - 🛰️ **Every cluster through one connection.** Point it at Proxmox Datacenter Manager and 89 tools reach every Proxmox VE cluster and Backup Server it manages, including cross-cluster migration. [More](#pdm)
  35. - 🧰 **The whole API, not a demo.** 346 tools across 14 areas: nodes, QEMU VMs, LXC containers, storage and backup, cluster and HA, access control, firewall, disks, Ceph, ACME, SDN, notifications, pools and appliances.
  36. - 🧭 **Workflows built in.** Five MCP prompts, such as a cluster health check and a snapshot-change-verify routine, plus live cluster state as MCP resources.
  37. - 🖥️ **Inside your guests too.** Run commands through the QEMU guest agent (`vm_agent_exec` → `vm_agent_exec_status`) and read back the exit code and output.
  38. - 🔒 **Look-but-don't-touch with one switch.** `PROXMOX_READ_ONLY=true` refuses every write inside the server, and the client sees only the 151 read-only tools.
  39. - 🧯 **Safe writes, protected guests.** `PROXMOX_NO_DESTRUCTIVE=true` hides the 73 tools that delete, stop, wipe or roll back. `PROXMOX_PROTECTED_VMIDS` names guests no tool may change.
  40. - ⏳ **Waits for the slow stuff.** Clone, migrate, backup and restore take `wait: true`, and `wait_for_task` follows any task to the end, with the log when it fails.
  41. - 🎯 **Load only what you use.** `PROXMOX_TOOLSETS=nodes,qemu,lxc,storage` cuts the tool list from 346 to 127, and the context it costs by more than half. Results come back as compact JSON.
  42. - 🚦 **Labelled for safe approval.** Every tool carries MCP `readOnlyHint` and `destructiveHint` annotations, so clients can auto-approve reads and ask before a delete, stop or rollback.
  43. - 🆕 **Current protocol, old clients welcome.** Built on MCP SDK 2: clients on the stateless 2026-07-28 protocol and on every handshake version back to 2024-11-05 connect. Failed calls are flagged as errors, so clients show them as failures.
  44. - 🔑 **API tokens or passwords.** Tokens are recommended; pair them with a `PVEAuditor` role for monitoring.
  45. - 🌐 **Local or on the network.** Clients spawn it over stdio, or `proxmox-mcp-server-http` serves it over streamable HTTP. Give each client its own token and a role: `read`, `operator` or `admin`.
  46. - 📜 **Every change on the record.** `PROXMOX_AUDIT_LOG` writes one JSON line per write call: who, what, the outcome and the task, with secrets redacted.
  47. - 🐳 **Runs anywhere.** Use `uv` from a clone, or the multi-arch image on `ghcr.io`.
  48. - ♻️ **Long sessions just work.** Password logins renew their Proxmox ticket before it expires.
  49. - 🤝 **A2A-ready.** `agent-card.json` lists every tool, Proxmox VE and Datacenter Manager, by skill category, for agent-to-agent discovery.
  50. - 🛡️ **Appliances.** `deploy_fortigate_vm` builds a FortiGate-VM from Fortinet's KVM image, with WAN/LAN NICs on the bridges and VLANs you choose. `deploy_cloud_vms` builds cluster-ready VMs from a cloud image, with your SSH key and a static IP each, ready for k3s-mcp-server's `create_cluster`.
  51. <a id="talk"></a>
  52. ## 💬 Talk to your cluster
  53. <p align="center">
  54. <img src="docs/chat.svg" width="100%" alt="A chat runs df -h inside VM 120 via the QEMU guest agent, with vm_agent_exec labelled destructive and vm_agent_exec_status labelled read-only, and shows the disk usage; a side panel cycles through more questions and the tools that answer them.">
  55. </p>
  56. Once it's connected, just ask:
  57. > *"Can you list all VMs in my Proxmox cluster?"*
  58. > *"What's the status of VM 100 on node pve1?"*
  59. > *"Create a snapshot called 'backup-2025' for VM 100 on pve1."*
  60. > *"Show me the storage usage on all nodes."*
  61. > *"List all running tasks in the cluster."*
  62. > *"Clone VM 9000 to a new VM called web-02 and start it."*
  63. > *"Run `df -h` inside VM 120 using the guest agent and show me the output."*
  64. > *"Make three Ubuntu VMs on pve1 at 192.168.1.181–183 with my SSH key, ready for a K3s cluster."*
  65. There are more worked examples in [USAGE.md](USAGE.md).
  66. <a id="prompts"></a>
  67. ### 🧭 Built-in prompts and resources
  68. <p align="center">
  69. <img src="docs/prompts.svg" width="100%" alt="Typing /mcp__proxmox__ in the client lists five prompts. Choosing cluster_health_check runs five read-only tools and the assistant reports one critical item, one warning and what is OK. Resources such as proxmox://cluster/resources attach live state without a tool call.">
  70. </p>
  71. The server ships **MCP prompts**, ready-made workflows your client lists by name. In Claude Code, type `/` to see them, for example `/mcp__proxmox__cluster_health_check`.
  72. | Prompt | What it does |
  73. |---|---|
  74. | `cluster_health_check` | Read-only check of quorum, nodes, guests, failed tasks, HA and Ceph, reported by severity |
  75. | `capacity_report` | Read-only storage, CPU and memory report with the biggest consumers; takes `threshold_percent` |
  76. | `safe_change` | Snapshot a guest, make your change after your go-ahead, verify it, and offer a rollback; takes `vmid` and `change` |
  77. | `investigate_failed_tasks` | Read-only: failed tasks, their logs, grouped by cause with fixes; takes `hours` |
  78. | `decommission_guest` | Back up, stop and delete a guest, asking before every change; takes `vmid` |
  79. Prompts only guide the model. Every step is still an ordinary tool call, so roles, read-only mode and protected guests apply as usual.
  80. **MCP resources** let a client attach live cluster state as context without spending tool calls:
  81. | Resource | Contents |
  82. |---|---|
  83. | `proxmox://cluster/status` | Quorum and node membership |
  84. | `proxmox://cluster/resources` | Every node, VM, container and storage with live usage |
  85. | `proxmox://cluster/tasks` | Recent tasks, with status |
  86. | `proxmox://nodes` | Nodes with CPU, memory and uptime |
  87. | `proxmox://storage` | Storage definitions |
  88. | `proxmox://nodes/{node}/status` | One node in detail |
  89. | `proxmox://vms/{node}/{vmid}/config`, `proxmox://cts/{node}/{vmid}/config` | One guest's configuration |
  90. Each resource is a single read, so resources work in read-only mode and for every role.
  91. <a id="how"></a>
  92. ## ⚙️ How it works
  93. <p align="center">
  94. <img src="docs/how-it-works.svg" width="100%" alt="MCP clients talk to proxmox-mcp-server over stdio or HTTP; the server calls the Proxmox VE API over HTTPS on port 8006. With read-only mode on, only the 150 read tools are listed, GET requests pass, and POST, PUT and DELETE are refused inside the server.">
  95. </p>
  96. - **Your MCP client** (Claude Desktop, Claude Code, or anything that speaks MCP) starts the server and talks to it over **stdio**. Or you run it as a service and clients connect over **[streamable HTTP](#http)**.
  97. - **`PROXMOX_TOOLSETS`** decides which API areas the server loads, and so which tools the client sees. Each tool is labelled read-only or destructive.
  98. - **The server** (Python, `httpx`, the MCP SDK) turns each tool call into a request to the **Proxmox VE REST API** over HTTPS on port **8006**, authenticated with an **API token** or a **password**.
  99. - **Read-only mode** hides the write tools and is also checked in the server's HTTP client, so a refused write never leaves your machine.
  100. <a id="tools"></a>
  101. ## 🧰 346 tools, 14 areas
  102. <p align="center">
  103. <img src="docs/tools.svg" width="100%" alt="A tile map of the 341 tools by toolset: QEMU VMs 46, nodes 38, cluster and HA 37, access control 33, Ceph 33, firewall 31, LXC 28, notifications 23, disks 17, ACME 17, SDN 16, storage and backup 14, pools 5, appliances 2, plus wait_for_task, which every toolset loads. Then all but nodes, qemu, lxc and storage dim, and the count drops to 127.">
  104. </p>
  105. | Area | Tools | Highlights |
  106. |------|------:|------------|
  107. | Nodes | 38 | Status, config, DNS/hosts/time, network interfaces, services, APT updates, syslog, power |
  108. | QEMU VMs | 46 | Lifecycle, create/clone/delete, config, snapshots, migration, disk resize/move, RRD metrics, guest agent (`vm_agent_exec`, `vm_agent_exec_status`), VNC proxy |
  109. | LXC containers | 28 | Lifecycle, create/clone/delete, config, snapshots, migration, resize |
  110. | Storage & backup | 14 | Storage definitions, content and volumes, URL downloads, `vzdump` backup and restore |
  111. | Cluster | 37 | Status, resources, options, log, tasks, HA resources/groups, replication, backup jobs |
  112. | Access control | 33 | Users, API tokens, groups, roles, ACLs, realms |
  113. | Firewall | 31 | Cluster and node rules, security groups, aliases, IP sets, macros, logs (per-VM and per-container rules are in the guest modules) |
  114. | Disks | 17 | SMART, wipe, GPT init, LVM, LVM-thin, ZFS, directory storage |
  115. | Ceph | 33 | Status, OSDs, monitors, managers, MDS, pools, flags, CRUSH |
  116. | ACME & certificates | 17 | ACME accounts and plugins, node certificate ordering, custom certs |
  117. | SDN | 16 | Zones, VNets, subnets, apply |
  118. | Notifications | 23 | Gotify, sendmail, SMTP and webhook endpoints, matchers |
  119. | Pools | 5 | Resource pool CRUD |
  120. | Appliances | 2 | `deploy_fortigate_vm`: FortiGate-VM from Fortinet's KVM image, WAN/LAN NICs on chosen bridges and VLANs, sized for the free evaluation license. `deploy_cloud_vms`: VMs from a cloud image (e.g. Ubuntu's) with cloud-init user, SSH key and a static IP or DHCP each, disk grown and started |
  121. One more tool, `wait_for_task`, is loaded with every toolset. It waits for any Proxmox task to finish; see [Waiting for long tasks](#wait).
  122. Tool names follow the Proxmox API: `list_*`, `get_*`, `create_*`, `update_*`/`set_*`, `delete_*`, plus actions such as `start_vm`, `migrate_container` or `apply_sdn`. Each area is one module in [`proxmox_mcp/tools/`](proxmox_mcp/tools/). Your MCP client shows every tool with its full input schema, or you can list them all locally:
  123. ```bash
  124. uv run python -c "from proxmox_mcp.server import ALL_TOOLS; print('\n'.join(sorted(t.name for t in ALL_TOOLS)))"
  125. ```
  126. ### Handy recipes
  127. | Task | Tools |
  128. |------|-------|
  129. | Inventory | `list_nodes`, `get_cluster_resources`, `list_vms`, `list_containers`, `list_storage` |
  130. | VM lifecycle | `start_vm`, `shutdown_vm`, `stop_vm`, `reboot_vm`, `create_vm`, `clone_vm`, `migrate_vm` |
  131. | Disk images | `download_url_to_storage` with `content=import`, then `create_vm` with `scsi0=local-lvm:0,import-from=local:import/<image>`, or `import_vm_disk` |
  132. | Snapshots | `create_vm_snapshot`, `list_vm_snapshots`, `rollback_vm_snapshot`, `delete_vm_snapshot` |
  133. | Monitoring | `get_node_status`, `get_vm_status`, `get_vm_rrddata`, `get_node_storage_status` |
  134. | Tasks | `list_cluster_tasks`, `list_node_tasks`, `get_task_status`, `get_task_log` |
  135. | Guest agent | `vm_agent_exec` (returns a PID), then `vm_agent_exec_status` for the exit code and output |
  136. | Cluster nodes | `download_url_to_storage` for a cloud image with `content=import`, then `deploy_cloud_vms`; hand the IPs to [k3s-mcp-server](https://github.com/ry-ops/k3s-mcp-server)'s `create_cluster` |
  137. <a id="quick-start"></a>
  138. ## 🚀 Quick start
  139. You need **Python 3.10+** with [`uv`](https://github.com/astral-sh/uv), or Docker, and **Proxmox VE 6.0 or later**.
  140. **1. Make an API token.** In the Proxmox UI, go to **Datacenter → Permissions → API Tokens → Add**. For full access, uncheck *Privilege Separation* so the token inherits your user's permissions. Copy the secret; you won't see it again. The full token ID looks like `root@pam!automation`.
  141. **2. Run the server** with one of these:
  142. <details open>
  143. <summary><b>uv, from a clone</b></summary>
  144. ```bash
  145. curl -LsSf https://astral.sh/uv/install.sh | sh # if you don't have uv
  146. git clone https://github.com/ry-ops/proxmox-mcp-server && cd proxmox-mcp-server
  147. ./setup.sh # or: uv sync
  148. export PROXMOX_HOST="192.168.1.100"
  149. export PROXMOX_USER="root@pam"
  150. export PROXMOX_TOKEN_NAME="automation"
  151. export PROXMOX_TOKEN_VALUE="your-token-here"
  152. ./test-connection.sh # checks connection, auth and permissions
  153. ```
  154. A `.env` file in the project directory is loaded automatically; see [`.env.example`](.env.example).
  155. </details>
  156. <details>
  157. <summary><b>Docker</b></summary>
  158. A multi-arch image is published to GitHub Container Registry on every push to `main` and for each release tag:
  159. ```bash
  160. docker pull ghcr.io/ry-ops/proxmox-mcp-server:latest # or a version tag, e.g. :2.14.0
  161. docker run -i --rm --env-file .env ghcr.io/ry-ops/proxmox-mcp-server:latest
  162. ```
  163. MCP clients talk over stdio, so run the container interactively (`-i`). `docker-compose.yaml` does the same using your `.env`. To serve it over HTTP instead, see [Run it over HTTP](#http).
  164. </details>
  165. **3. Connect your MCP client.** For Claude Desktop, edit `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, or `%APPDATA%/Claude/claude_desktop_config.json` on Windows:
  166. <details open>
  167. <summary><b>uv + API token (recommended)</b></summary>
  168. ```json
  169. {
  170. "mcpServers": {
  171. "proxmox": {
  172. "command": "uv",
  173. "args": ["--directory", "/absolute/path/to/proxmox-mcp-server", "run", "proxmox-mcp-server"],
  174. "env": {
  175. "PROXMOX_HOST": "192.168.1.100",
  176. "PROXMOX_USER": "root@pam",
  177. "PROXMOX_TOKEN_NAME": "automation",
  178. "PROXMOX_TOKEN_VALUE": "your-token-value-here"
  179. }
  180. }
  181. }
  182. }
  183. ```
  184. Use the **absolute** path to your clone.
  185. </details>
  186. <details>
  187. <summary><b>uv + password</b></summary>
  188. ```json
  189. {
  190. "mcpServers": {
  191. "proxmox": {
  192. "command": "uv",
  193. "args": ["--directory", "/absolute/path/to/proxmox-mcp-server", "run", "proxmox-mcp-server"],
  194. "env": {
  195. "PROXMOX_HOST": "192.168.1.100",
  196. "PROXMOX_USER": "root@pam",
  197. "PROXMOX_PASSWORD": "your-password-here"
  198. }
  199. }
  200. }
  201. }
  202. ```
  203. </details>
  204. <details>
  205. <summary><b>Docker</b></summary>
  206. ```json
  207. {
  208. "mcpServers": {
  209. "proxmox": {
  210. "command": "docker",
  211. "args": ["run", "-i", "--rm",
  212. "-e", "PROXMOX_HOST", "-e", "PROXMOX_USER", "-e", "PROXMOX_TOKEN_NAME", "-e", "PROXMOX_TOKEN_VALUE",
  213. "ghcr.io/ry-ops/proxmox-mcp-server:latest"],
  214. "env": {
  215. "PROXMOX_HOST": "192.168.1.100",
  216. "PROXMOX_USER": "root@pam",
  217. "PROXMOX_TOKEN_NAME": "automation",
  218. "PROXMOX_TOKEN_VALUE": "your-token-value-here"
  219. }
  220. }
  221. }
  222. }
  223. ```
  224. </details>
  225. <details>
  226. <summary><b>Claude Code</b></summary>
  227. ```bash
  228. claude mcp add proxmox \
  229. -e PROXMOX_HOST=192.168.1.100 -e PROXMOX_USER=root@pam \
  230. -e PROXMOX_TOKEN_NAME=automation -e PROXMOX_TOKEN_VALUE=your-token-value-here \
  231. -- uv --directory /absolute/path/to/proxmox-mcp-server run proxmox-mcp-server
  232. ```
  233. Add `-e PROXMOX_TOOLSETS=nodes,qemu,lxc,storage` to keep the tool list small. For a server you run over HTTP, see [Run it over HTTP](#http).
  234. </details>
  235. **4. Restart your client completely** (quit it, don't just close the window), and ask it to list your VMs. More detail in [QUICKSTART.md](QUICKSTART.md) and [SETUP.md](SETUP.md).
  236. <a id="clusters"></a>
  237. ### 🏢 Several clusters
  238. Run one server per cluster, each under its own name. Every cluster then gets its own credentials, toolsets, safety settings and audit log, and the assistant always knows which cluster a tool acts on, because the tool names carry the server name (`mcp__proxmox-lab__start_vm` and `mcp__proxmox-prod__start_vm`).
  239. ```json
  240. {
  241. "mcpServers": {
  242. "proxmox-lab": {
  243. "command": "uv",
  244. "args": ["--directory", "/absolute/path/to/proxmox-mcp-server", "run", "proxmox-mcp-server"],
  245. "env": { "PROXMOX_HOST": "10.0.10.5", "PROXMOX_USER": "root@pam",
  246. "PROXMOX_TOKEN_NAME": "automation", "PROXMOX_TOKEN_VALUE": "lab-token" }
  247. },
  248. "proxmox-prod": {
  249. "command": "uv",
  250. "args": ["--directory", "/absolute/path/to/proxmox-mcp-server", "run", "proxmox-mcp-server"],
  251. "env": { "PROXMOX_HOST": "10.0.20.5", "PROXMOX_USER": "mcp@pve",
  252. "PROXMOX_TOKEN_NAME": "readonly", "PROXMOX_TOKEN_VALUE": "prod-token",
  253. "PROXMOX_NO_DESTRUCTIVE": "true", "PROXMOX_PROTECTED_VMIDS": "100-110",
  254. "PROXMOX_TOOLSETS": "nodes,qemu,lxc,storage" }
  255. }
  256. }
  257. }
  258. ```
  259. Give each extra cluster only the toolsets it needs, because every server's tools count against the client's context. Over HTTP, run one `proxmox-mcp-server-http` per cluster on its own port.
  260. <a id="deploy"></a>
  261. ### 🧑‍🚀 Deploy an OS by asking
  262. <p align="center">
  263. <img src="docs/deploy.svg" width="100%" alt="You ask for a Kali VM and the server runs deploy_kali_vm: it fetches Kali's official cloud image and checks its SHA-256, repacks the sparse 25 GiB disk as a 1.06 GiB qcow2, builds a cloud-init seed ISO, creates and boots VM 120, waits for the guest agent to report 10.0.0.77, and deletes the seed ISO. Below, Ubuntu, Kali, Windows 11 and Datacenter Manager build side by side, each finishing with how to reach the machine.">
  264. </p>
  265. Ask for a VM by name and the server does the rest: fetches the official image (checksum verified, cached on storage and reused), builds a small seed ISO with the first-boot settings, creates and starts the VM, waits until its guest agent answers, and reports how to reach it.
  266. | Tool | What you get |
  267. |---|---|
  268. | `deploy_ubuntu_vm` | Ubuntu 24.04 LTS from the official cloud image |
  269. | `deploy_kali_vm` | Kali Linux from its official cloud image. It ships as `.tar.xz`, which Proxmox can't import, so the server repacks its sparse 25 GiB disk as qcow2 and uploads only the ≈1 GiB of data |
  270. | `deploy_pdm_vm` | Proxmox Datacenter Manager on a Debian 13 VM, installed by cloud-init from the no-subscription repository; reports `https://<ip>:8443` and the `root@pam` login |
  271. | `deploy_windows11_vm` | Windows 11 installed unattended: q35, UEFI, Secure Boot keys, TPM 2.0, VirtIO disk and network, VirtIO guest tools. Uses a Windows 11 ISO already on storage (Microsoft has no stable download link); installs without a product key, so activation is yours |
  272. | `list_os_images` | What's cached on the node, and with `check_upstream`, the latest official versions |
  273. Give an SSH public key, or the tool generates a password and returns it once (the audit log redacts passwords). The seed ISO holds those credentials, so it's deleted as soon as the guest is up. Each tool takes the usual sizing and network inputs (`cores`, `memory`, `disk_gb`, `bridge`, `vlan`, a static `ip` or DHCP) and `wait_until_ready` / `ready_timeout`. Windows Setup takes 20 to 40 minutes; with a shorter timeout the tool returns `installing` and says what to clean up after.
  274. <a id="pdm"></a>
  275. ### 🛰️ Proxmox Datacenter Manager
  276. <p align="center">
  277. <img src="docs/pdm.svg" width="100%" alt="proxmox-mcp's pdm toolset connects to Proxmox Datacenter Manager with an API token. One pdm_list_resources call fans out to three remotes and returns their guests, nodes and datastores. pdm_pve_remote_migrate_guest moves web-01 from pve-lab to the pve-prod cluster. pdm_pve_stop_guest on the protected guest pve-lab:104 is refused, and pdm_collect_metrics, which PDM reserves for root@pam, explains the elevated permission it needs.">
  278. </p>
  279. If you run [Proxmox Datacenter Manager](https://pdm.proxmox.com/) (PDM), point the server at it and the `pdm` toolset loads: 89 tools that reach every Proxmox VE cluster and Proxmox Backup Server PDM manages, through one connection. It can run alongside a direct Proxmox VE connection, or on its own.
  280. - **Across everything:** resources, top consumers, tasks, pending updates and subscriptions for all remotes at once.
  281. - **Per remote:** nodes, guests, configs, snapshots, storage, firewall, tasks and metrics on Proxmox VE remotes; datastores, namespaces, snapshots and tasks on Backup Server remotes; SDN and Ceph.
  282. - **Actions:** start, stop, shut down and resume guests; create, delete, roll back and describe snapshots; migrate within a cluster or **to another cluster** (`pdm_pve_remote_migrate_guest`); stop tasks; refresh updates, task caches and metrics. Actions take `wait`.
  283. Tools that cover both VMs and containers take `type` (`qemu` or `lxc`). Every input is checked against PDM's own schema before a request is sent.
  284. ```json
  285. "env": {
  286. "PDM_HOST": "10.0.0.20",
  287. "PDM_TOKEN_ID": "root@pam!proxmox-mcp",
  288. "PDM_TOKEN_SECRET": "…",
  289. "PDM_CA_BUNDLE": "/path/to/pdm-api.pem",
  290. "PDM_TLS_NAME": "pdm",
  291. "PDM_PROTECTED_GUESTS": "pve01:104,pve01:105"
  292. }
  293. ```
  294. Create the token in PDM under **Configuration → Access Control → API Tokens**, then give it roles under **Permissions**. PDM tokens start with no permissions, and never get more than their user:
  295. | Path | Role | Covers |
  296. |---|---|---|
  297. | `/resource` | **Auditor** for read-only, **Administrator** for actions | Every remote: reads need `Resource.Audit`; actions need `Resource.Manage` (power, snapshots, stopping tasks), `Resource.Modify` (refreshing package lists) and `Resource.Migrate` |
  298. | `/system` | **Auditor** | `pdm_node_status` (the PDM host's own usage) |
  299. Seven tools reach endpoints PDM 1.1 allows only for `root@pam` logged in with a password, so with an API token they return 403 whatever its roles: `pdm_pve_list_remotes` and `pdm_pbs_list_remotes` (use `pdm_list_remotes` instead), `pdm_metric_collection_status`, `pdm_collect_metrics`, `pdm_get_remote_rrddata`, and the two EVPN lookups. Their descriptions say so, and when PDM refuses one, the error explains the elevated permissions it needs and what to use instead.
  300. PDM can also protect a guest itself: a **NoAccess** entry for the token on `/resource/<remote>/guest/<vmid>` (for example `/resource/pve01/guest/104`) makes PDM refuse every call about that guest, whatever this server does. For `PDM_CA_BUNDLE`, copy `/etc/proxmox-datacenter-manager/auth/api.pem` from the PDM host. Its self-signed certificate names `pdm` and `localhost`, not the host's IP, so when `PDM_HOST` is an IP also set `PDM_TLS_NAME=pdm`: the certificate is checked against that name while the server connects to the IP.
  301. **Protected guests.** VMIDs are only unique within a cluster, so PDM tools use `PDM_PROTECTED_GUESTS`, with the remote in each entry: `pve01:104`, or `*:9000-9010` for every remote. A migration is refused when its source or its target is protected. `PROXMOX_PROTECTED_VMIDS` doesn't apply to PDM tools. `PROXMOX_READ_ONLY`, `PROXMOX_NO_DESTRUCTIVE`, HTTP roles and the audit log apply as usual.
  302. The tools are generated from PDM's published API schema; [ROADMAP.md](ROADMAP.md) maps all 327 PDM endpoints and what's planned next.
  303. ## 🔧 Configuration
  304. | Variable | Required | Default | What it does |
  305. |---|:---:|---|---|
  306. | `PROXMOX_HOST` | ✅¹ | | Hostname or IP, **without** scheme or port (`192.168.1.100`, not `https://192.168.1.100:8006`) |
  307. | `PROXMOX_USER` | ✅¹ | | e.g. `root@pam`, `admin@pve` |
  308. | `PROXMOX_TOKEN_NAME` + `PROXMOX_TOKEN_VALUE` | one of | | API token auth (recommended) |
  309. | `PROXMOX_PASSWORD` | one of | | Password auth |
  310. | `PROXMOX_PORT` | | `8006` | API port |
  311. | `PROXMOX_VERIFY_SSL` | | `false` | Verify the server's TLS certificate against the system's trusted CAs |
  312. | `PROXMOX_CA_BUNDLE` | | | CA file to verify against instead, e.g. a copy of `/etc/pve/pve-root-ca.pem`; works with Proxmox's default self-signed certificates |
  313. | `PROXMOX_READ_ONLY` | | `false` | Refuse every write and advertise only read tools; see below |
  314. | `PROXMOX_TOOLSETS` | | all | Comma-separated API areas to load; see below |
  315. | `PROXMOX_NO_DESTRUCTIVE` | | `false` | Hide the 73 tools that delete, stop, wipe or roll back; see [Safety](#read-only) |
  316. | `PROXMOX_PROTECTED_VMIDS` | | | Guest IDs and ranges no tool may change, e.g. `100,101,9000-9010` |
  317. | `PROXMOX_WAIT_TIMEOUT` | | `900` | Seconds a `wait` lasts before it returns with the task still running |
  318. | `MCP_HTTP_HOST` | | `127.0.0.1` | HTTP entrypoint only: bind address |
  319. | `MCP_HTTP_PORT` | | `8811` | HTTP entrypoint only: port |
  320. | `MCP_AUTH_TOKEN` | | | HTTP entrypoint only: one admin bearer token; a token is required off loopback |
  321. | `MCP_AUTH_TOKENS` | | | HTTP entrypoint only: several tokens with roles, `name:role:token,…`; see [Roles](#roles) |
  322. | `MCP_AUTH_TOKENS_FILE` | | | HTTP entrypoint only: the same, one `name role token` per line |
  323. | `PROXMOX_AUDIT_LOG` | | | File, or `stderr`, for a JSON-lines log of every write call; see [Audit log](#audit) |
  324. | `PROXMOX_AUDIT_READS` | | `false` | Log read calls too |
  325. | `MCP_HTTP_ALLOW_NO_AUTH` | | `false` | HTTP entrypoint only: allow a non-loopback address with no token |
  326. | `PDM_HOST` | ✅¹ | | Proxmox Datacenter Manager hostname or IP; loads the `pdm` toolset. See [Datacenter Manager](#pdm) |
  327. | `PDM_PORT` | | `8443` | PDM API port |
  328. | `PDM_TOKEN_ID` + `PDM_TOKEN_SECRET` | with `PDM_HOST` | | PDM API token, `user@realm!name`, and its secret |
  329. | `PDM_CA_BUNDLE` | | | PDM's certificate (or its CA) to verify against |
  330. | `PDM_TLS_NAME` | | | Name to check PDM's certificate against when `PDM_HOST` is an IP it doesn't name, e.g. `pdm` |
  331. | `PDM_VERIFY_SSL` | | `false` | Verify PDM's certificate against the system's trusted CAs instead |
  332. | `PDM_PROTECTED_GUESTS` | | | `remote:ID` entries PDM tools may not change, e.g. `pve01:104,*:9000-9010` |
  333. ¹ Set `PROXMOX_HOST` (with `PROXMOX_USER` and a token or password) to talk to Proxmox VE directly, `PDM_HOST` to go through Datacenter Manager, or both.
  334. <a id="toolsets"></a>
  335. ### 🎯 Toolsets: load only what you use
  336. Every tool the server advertises sits in the client's context on every turn, and all 346 schemas come to roughly 44k tokens. Set `PROXMOX_TOOLSETS` to the areas you need:
  337. ```bash
  338. PROXMOX_TOOLSETS=nodes,qemu,lxc,storage
  339. ```
  340. | Setting | Tools | Approx. tokens |
  341. |---|--:|--:|
  342. | all (default) | 346 | 44k |
  343. | `PROXMOX_NO_DESTRUCTIVE=true` | 273 | 35k |
  344. | `nodes,qemu,lxc,storage,cluster` | 164 | 23k |
  345. | `nodes,qemu,lxc,storage` | 127 | 19k |
  346. | `PROXMOX_READ_ONLY=true` | 151 | 13k |
  347. | `qemu` | 47 | 8k |
  348. Every count includes `wait_for_task`, which loads with any selection.
  349. The names are `nodes`, `qemu`, `lxc`, `storage`, `cluster`, `access`, `firewall`, `disks`, `ceph`, `acme`, `sdn`, `notifications`, `pools` and `appliances`. `vms` and `containers` work as aliases for `qemu` and `lxc`. A misspelt name stops the server at startup with the list of valid ones. Toolsets combine with read-only mode.
  350. ### 🚦 Tool annotations
  351. Each tool tells the client what it does, through standard MCP annotations:
  352. - **`readOnlyHint: true`** on the 151 tools that only read.
  353. - **`destructiveHint: true`** on the 73 that delete, stop, wipe, roll back, restore over, or run commands in a guest.
  354. - **`destructiveHint: false`** on the other writes, such as create, start or update.
  355. A test sends every tool through a recording client and checks its read-only label against the HTTP methods it sends, so the labels can't drift from the code.
  356. <a id="http"></a>
  357. ### 🌐 Run it over HTTP
  358. `proxmox-mcp-server-http` serves the same tools over MCP streamable HTTP at `/mcp`, so the server can run as a network service instead of a process each client spawns. `PROXMOX_TOOLSETS` and `PROXMOX_READ_ONLY` apply as usual, and `/healthz` answers without auth for container health checks.
  359. ```bash
  360. # Local only, no token needed:
  361. uv run proxmox-mcp-server-http # http://127.0.0.1:8811/mcp
  362. # On the network, a token is required:
  363. MCP_HTTP_HOST=0.0.0.0 MCP_AUTH_TOKEN="$(openssl rand -hex 32)" uv run proxmox-mcp-server-http
  364. ```
  365. The same image runs it in Docker:
  366. ```bash
  367. docker run -p 8811:8811 --env-file .env -e MCP_HTTP_HOST=0.0.0.0 -e MCP_AUTH_TOKEN \
  368. ghcr.io/ry-ops/proxmox-mcp-server:latest proxmox-mcp-server-http
  369. ```
  370. Clients send `Authorization: Bearer <token>`. For Claude Code:
  371. ```bash
  372. claude mcp add --transport http proxmox http://pve-mcp.lan:8811/mcp \
  373. --header "Authorization: Bearer $MCP_AUTH_TOKEN"
  374. ```
  375. **Anyone who can reach this endpoint can use every loaded tool with your Proxmox credentials.** So the server binds to `127.0.0.1` by default. It refuses any other address unless a token is set, or you opt out with `MCP_HTTP_ALLOW_NO_AUTH=true` because a proxy in front of it authenticates clients. The token check runs in constant time. On loopback, DNS-rebinding protection rejects requests whose Host header isn't a local address. Put TLS in front of it, for example with a reverse proxy, when the token crosses a network.
  376. <a id="roles"></a>
  377. #### 🎭 One token per client, each with a role
  378. <p align="center">
  379. <img src="docs/http-roles.svg" width="100%" alt="Four clients call the HTTP server: ops with the admin role sees 341 tools, ci with the operator role sees 268, grafana with the read role sees 150, and a client with no token gets 401. The audit log records ci's clone as ok and grafana's stop_vm as refused.">
  380. </p>
  381. Give every client its own token, so you can tell them apart in the [audit log](#audit) and revoke one without the others. Each token carries a role:
  382. | Role | Can use |
  383. |---|---|
  384. | `read` | only tools that read, like a dashboard or a monitoring agent |
  385. | `operator` | everything except destructive tools: start, create, clone, snapshot, migrate |
  386. | `admin` | everything the server loads |
  387. ```bash
  388. MCP_AUTH_TOKENS="ops:admin:$(openssl rand -hex 32),grafana:read:$(openssl rand -hex 32)"
  389. # or a file with one "name role token" per line, comments with #:
  390. MCP_AUTH_TOKENS_FILE=/run/secrets/proxmox-mcp-tokens
  391. ```
  392. Each client sees only the tools its role allows, and a call outside its role is refused before anything reaches Proxmox. Roles only narrow what the server already allows: `PROXMOX_READ_ONLY`, `PROXMOX_NO_DESTRUCTIVE`, toolsets and protected guests still apply to everyone. Tokens must be at least 16 characters, and names and tokens must be unique. `MCP_AUTH_TOKEN` still works, as an admin token named `default`.
  393. <a id="wait"></a>
  394. ### ⏳ Waiting for long tasks
  395. <p align="center">
  396. <img src="docs/wait.svg" width="100%" alt="clone_vm with wait: true returns the finished task's outcome in one call. A backup outlasts the timeout and returns status running; wait_for_task then follows it to OK.">
  397. </p>
  398. Clone, migrate, backup, restore, disk moves, snapshots and power actions start a Proxmox task and return its ID, a UPID. Pass `wait: true` to any of these 30 tools and the result also carries the task's outcome:
  399. ```json
  400. {"data":"UPID:pve2:0003A1B2:…:qmclone:9000:root@pam:","task":{"status":"stopped","exitstatus":"OK","ok":true}}
  401. ```
  402. `wait_for_task` does the same for any UPID, including ones from the cluster task list. A failed task includes the last 20 lines of its log. A wait never fails just because a task is slow. After `PROXMOX_WAIT_TIMEOUT` seconds, 900 by default, it returns `status: "running"`, and calling `wait_for_task` again keeps waiting.
  403. <a id="read-only"></a>
  404. ## 🔒 Safety: read-only mode, destructive tools and protected guests
  405. <p align="center">
  406. <img src="docs/safety.svg" width="100%" alt="Bars show 341 tools by default, 268 with PROXMOX_NO_DESTRUCTIVE and 150 with PROXMOX_READ_ONLY. Guests 100 and 101 are protected: stop_vm on 120 succeeds, delete_vm on 100 and node_stopall without a list are refused, and each call lands in the audit log.">
  407. </p>
  408. **`PROXMOX_READ_ONLY=true`** makes the server look-but-don't-touch. Only GET requests are sent, and every create, update, delete or action tool is refused inside the server before it reaches the network. **The client sees only the 151 read-only tools**, so it never plans around a tool that would be refused. Three read-style tools send POST requests, so they're hidden too:
  409. - `vm_agent_ping`;
  410. - `get_vm_vnc_proxy` and `get_vm_spice_proxy`, which create console access tickets.
  411. **`PROXMOX_NO_DESTRUCTIVE=true`** is the middle ground. It hides the 73 tools labelled destructive: deleting, stopping, wiping, rolling back, restoring over a guest, and running commands inside one. Safe writes such as start, create, clone, snapshot and config changes stay available, so 268 tools remain.
  412. **`PROXMOX_PROTECTED_VMIDS=100,101,9000-9010`** names guests no tool may change, such as your router, DNS or backup server. The server checks every write before sending it: power actions, config changes, snapshots, migration, disk moves, deletion, guest-agent commands, HA changes, and deleting the guest's volumes or backups. Reads always work. Cloning from a protected template, backing it up and opening its console stay allowed, because they leave it as it is. Node-wide and bulk start, stop and migrate actions need an explicit `vms` list while any guest is protected, since they would otherwise include it. Whole-node shutdown and reboot are not covered.
  413. <a id="audit"></a>
  414. **`PROXMOX_AUDIT_LOG=/var/log/proxmox-mcp/audit.jsonl`** records every write call as one JSON line, whether it succeeded, failed or was refused. Set it to `stderr` to send the lines to your container logs instead. `PROXMOX_AUDIT_READS=true` logs reads too.
  415. ```json
  416. {"ts":"2026-10-30T21:04:12.418+00:00","who":"ci","via":"http","tool":"clone_vm","args":{"node":"pve2","vmid":9000,"newid":123},"outcome":"ok","upid":"UPID:pve2:…","task_ok":true,"ms":41873}
  417. {"ts":"2026-10-30T21:05:02.007+00:00","who":"grafana","via":"http","tool":"stop_vm","args":{"node":"pve1","vmid":120},"outcome":"refused","error":"stop_vm is not allowed for grafana (role: read)","ms":0}
  418. ```
  419. Arguments whose names look secret, such as passwords, tokens, private keys and cloud-init passwords, are written as `***`. A failure to write the log is reported on stderr and never fails the tool call.
  420. The rest of the security picture:
  421. - **For monitoring-only use, combine both locks:** `PROXMOX_READ_ONLY=true` *and* a token with the **`PVEAuditor`** role. The flag stops the server sending writes; the role makes Proxmox refuse them anyway.
  422. - **The token's permissions are the real limit.** The server exposes destructive operations: deleting VMs, wiping disks, and running commands inside guests. Whatever the token can do, a connected AI client can ask for. Grant the minimum.
  423. - **Prefer API tokens** over passwords. They can be revoked on their own.
  424. - **Verify the TLS certificate.** Without it, anyone on the network path can read the token. With Proxmox's default self-signed certificates, copy `/etc/pve/pve-root-ca.pem` from any node and set `PROXMOX_CA_BUNDLE` to it; with a publicly trusted certificate, set `PROXMOX_VERIFY_SSL=true`. The server prints a warning at startup when neither is set.
  425. - **Keep credentials out of version control**, and restrict network access to the API with firewall rules.
  426. <a id="a2a"></a>
  427. ## 🤝 Agent-to-agent (A2A)
  428. [`agent-card.json`](agent-card.json) is this server's identity and capability manifest for other agents. It lists **all 346 Proxmox VE tools in 14 skill categories, plus the 89 Datacenter Manager tools**, each with its name, description, inputs, and `read_only` and `destructive` flags. A test fails if it drifts from the tool registry. It also covers authentication requirements and MCP protocol details.
  429. | Category | Tools | Category | Tools |
  430. |---|--:|---|--:|
  431. | `node_management` | 38 | `disk_management` | 17 |
  432. | `virtual_machine_management` | 46 | `ceph_management` | 33 |
  433. | `container_management` | 28 | `certificate_management` | 17 |
  434. | `storage_management` | 14 | `sdn_management` | 16 |
  435. | `cluster_management` | 38 | `notification_management` | 23 |
  436. | `access_control` | 33 | `pool_management` | 5 |
  437. | `firewall_management` | 31 | `appliances` | 2 |
  438. <details>
  439. <summary><b>Discover the agent's skills</b></summary>
  440. ```python
  441. import json
  442. with open('agent-card.json') as f:
  443. agent_card = json.load(f)
  444. print(f"Agent: {agent_card['name']} Version: {agent_card['version']}")
  445. for skill in agent_card['skills']:
  446. print(f"\n{skill['category']}:")
  447. for capability in skill['capabilities']:
  448. print(f" - {capability['name']}: {capability['description']}")
  449. ```
  450. </details>
  451. <details>
  452. <summary><b>Call its tools over MCP</b></summary>
  453. ```python
  454. from mcp import ClientSession, StdioServerParameters
  455. from mcp.client.stdio import stdio_client
  456. server_params = StdioServerParameters(
  457. command="uv",
  458. args=["--directory", "/path/to/proxmox-mcp-server", "run", "proxmox-mcp-server"],
  459. env={
  460. "PROXMOX_HOST": "192.168.1.100",
  461. "PROXMOX_USER": "root@pam",
  462. "PROXMOX_TOKEN_NAME": "automation",
  463. "PROXMOX_TOKEN_VALUE": "your-token-value",
  464. },
  465. )
  466. async with stdio_client(server_params) as (read, write):
  467. async with ClientSession(read, write) as session:
  468. await session.initialize()
  469. tools = await session.list_tools()
  470. result = await session.call_tool("list_vms", arguments={})
  471. print(result.content)
  472. ```
  473. </details>
  474. <details>
  475. <summary><b>Orchestrate it with other agents</b></summary>
  476. ```python
  477. # Snapshot every VM, then hand off to other agents
  478. async def backup_workflow():
  479. vms = await proxmox_agent.call_tool("list_vms", {})
  480. for vm in vms['data']:
  481. await proxmox_agent.call_tool("create_vm_snapshot", {
  482. "node": vm['node'],
  483. "vmid": vm['vmid'],
  484. "snapname": f"backup-{datetime.now():%Y%m%d-%H%M%S}",
  485. })
  486. await storage_agent.call_tool("check_capacity", {})
  487. await notification_agent.call_tool("send_alert", {"message": f"Backup completed: {len(vms['data'])} VMs"})
  488. ```
  489. </details>
  490. <a id="troubleshooting"></a>
  491. ## 🩺 Troubleshooting
  492. <details>
  493. <summary><b>Authentication errors</b></summary>
  494. - Double-check the credentials and that the user has the permissions you need.
  495. - For API tokens, make sure the token hasn't expired or been revoked.
  496. - If the token was created with *Privilege Separation* on, give the token its own permissions, or recreate it with that option off.
  497. </details>
  498. <details>
  499. <summary><b>Connection errors</b></summary>
  500. - Check `PROXMOX_HOST` (no scheme, no port) and `PROXMOX_PORT`.
  501. - Check you can reach the host: `curl -k https://YOUR_HOST:8006/api2/json/version`
  502. - If `PROXMOX_VERIFY_SSL=true` or `PROXMOX_CA_BUNDLE` is set, the certificate must be valid for `PROXMOX_HOST`. Proxmox's node certificates name the node's hostname and IP addresses, so use one of those.
  503. </details>
  504. <details>
  505. <summary><b>Permission errors</b></summary>
  506. The user or token needs privileges for each operation. Common ones: `VM.Monitor`, `VM.Audit`, `Datastore.Audit`, `Sys.Audit`, `VM.PowerMgmt`, `VM.Snapshot`.
  507. </details>
  508. <details>
  509. <summary><b>Tools don't show up in Claude</b></summary>
  510. - The path in the config must be **absolute**.
  511. - The config file must be valid JSON.
  512. - Quit Claude Desktop completely and start it again.
  513. - Check Claude Desktop's logs. The server logs its authentication method and connection status to stderr, which shows up there.
  514. </details>
  515. <details>
  516. <summary><b>A tool is missing, or "Unknown or disabled tool"</b></summary>
  517. - `PROXMOX_TOOLSETS` loads only the areas it names. Add the area, or remove the variable to load all of them.
  518. - `PROXMOX_READ_ONLY=true` hides every write tool. Set it to `false` to create, change or delete.
  519. - `PROXMOX_NO_DESTRUCTIVE=true` hides the delete, stop, wipe and rollback tools.
  520. - "guest … is protected" means `PROXMOX_PROTECTED_VMIDS` covers that guest.
  521. - The server logs how many tools it loaded, and from which toolsets, to stderr at startup.
  522. </details>
  523. <details>
  524. <summary><b>HTTP: 401, 421, or the server won't start</b></summary>
  525. - **401 Unauthorized**: the client must send `Authorization: Bearer <token>` with one of the configured tokens.
  526. - **"… is not allowed for NAME (role: read)"**: that client's token has a role that excludes the tool. Use a token with a wider role.
  527. - **421 Misdirected Request**: on `127.0.0.1` the server only accepts local Host headers. Connect to `127.0.0.1` or `localhost`, or bind to another address with a token.
  528. - **"Refusing to serve on 0.0.0.0 without authentication"**: set `MCP_AUTH_TOKEN` or `MCP_AUTH_TOKENS`, or `MCP_HTTP_ALLOW_NO_AUTH=true` if a proxy in front authenticates clients.
  529. </details>
  530. <details>
  531. <summary><b>Check the connection before involving Claude</b></summary>
  532. ```bash
  533. ./test-connection.sh
  534. ```
  535. It checks the connection, the API, authentication, permission to list nodes, and access to cluster resources.
  536. </details>
  537. ## 🛠️ Development
  538. ```bash
  539. uv sync # dependencies, including dev tools
  540. uv run proxmox-mcp-server # run the server directly (stdio)
  541. uv run proxmox-mcp-server-http # or over streamable HTTP
  542. uv run pytest # tests
  543. uv run ruff check . && uv run black .
  544. ```
  545. ```
  546. proxmox_mcp/
  547. ├── server.py stdio entrypoint: tool calls, roles, guards, waits, audit
  548. ├── server_http.py streamable-HTTP entrypoint: bearer tokens, loopback default
  549. ├── registry.py toolsets, read-only and no-destructive filtering, annotations
  550. ├── auth.py HTTP tokens and roles
  551. ├── audit.py JSON-lines audit log
  552. ├── guards.py protected guests
  553. ├── tasks.py waiting for Proxmox tasks
  554. ├── prompts.py MCP prompts: built-in workflows
  555. ├── resources.py MCP resources: read-only cluster views
  556. ├── client.py Proxmox API client: token/password auth, ticket renewal, read-only guard
  557. └── tools/ one module per API area:
  558. nodes, qemu, lxc, storage, cluster, access, firewall,
  559. disks, ceph, acme, sdn, notifications, pools, appliances
  560. tests/ pytest suite, run in CI on Python 3.10–3.13
  561. docs/ the animations on this page; docs/gen/build.py regenerates four of them
  562. agent-card.json A2A agent card
  563. Dockerfile, docker-compose.yaml, setup.sh, test-connection.sh
  564. QUICKSTART.md · SETUP.md · USAGE.md · CHANGELOG.md
  565. ```
  566. **Dependencies:**
  567. - **`mcp`** (>=2.3, <3): the MCP SDK. It serves both the handshake protocol (2024-11-05 to 2025-11-25) and the stateless 2026-07-28 protocol, so older and newer clients both connect.
  568. - **`httpx`**: the async HTTP client.
  569. - **`python-dotenv`**: loads `.env`.
  570. - **`starlette`** and **`uvicorn`**: serve the HTTP entrypoint. `mcp` already depends on both.
  571. ## 🗺️ Roadmap
  572. - One server for several clusters without Datacenter Manager, chosen per call (today: [one server per cluster](#clusters), or [through PDM](#pdm))
  573. - Progress notifications while waiting for long tasks
  574. What has shipped is in [CHANGELOG.md](CHANGELOG.md).
  575. ## 🙌 Contributing
  576. Issues and pull requests are welcome: new tools, better error handling, performance, docs, tests and bug fixes.
  577. ## 📚 Learn more
  578. - [Proxmox VE API](https://pve.proxmox.com/wiki/Proxmox_VE_API) · [API viewer](https://pve.proxmox.com/pve-docs/api-viewer/) · [Admin guide](https://pve.proxmox.com/pve-docs/pve-admin-guide.html)
  579. - [Model Context Protocol](https://modelcontextprotocol.io/) · [MCP servers](https://github.com/modelcontextprotocol/servers) · [uv](https://github.com/astral-sh/uv)
  580. ## License
  581. MIT. See [LICENSE](LICENSE).
  582. <!-- org-footer -->
  583. ---
  584. <p align="center"><sub>Part of <a href="https://github.com/ry-ops">ry-ops</a> · building the pipes between infrastructure, automation, and observability · built by <a href="https://github.com/ry-ops">ry-ops</a></sub></p>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.