Skip to content
Back to search

ProxmoxMCP-Plus

Use MCP and OpenAPI to safely control Proxmox VE VMs, LXCs, backups, and snapshots from LLMs and AI agents.

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/RekklesNA/ProxmoxMCP-Plus 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/RekklesNA/ProxmoxMCP-Plus'

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/rekklesna--proxmoxmcp-plus/badge.svg)](/listings/rekklesna--proxmoxmcp-plus)

HTML

<a href="/listings/rekklesna--proxmoxmcp-plus"><img src="/api/listings/rekklesna--proxmoxmcp-plus/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.

1. Prepare Proxmox Credentials

Create a Proxmox API token with only the permissions your workflows need. Then create the local config file:

cp proxmox-config/config.example.json proxmox-config/config.json

Then edit `proxmox-config/config.json` with your environment. At minimum, it needs:

- `proxmox.host` - `proxmox.port` - `auth.user` - `auth.token_name` - `auth.token_value`

Add an `ssh` section as well if you want container command execution. Add a `jobs` section if you want job state persisted somewhere other than the default local SQLite file.

For real live verification, use a separate `proxmox-config/config.live.json` created from `proxmox-config/config.live.example.json`. Do not point live e2e at a placeholder or local-only `config.json` unless you intentionally run a local API tunnel there.

Optional job persistence config:

{
  "jobs": {
    "sqlite_path": "proxmox-jobs.sqlite3"
  }
}

Optional tool exposure filtering can reduce the schemas sent to MCP clients. It is disabled by default, so existing configurations continue to expose every available tool. Configure exactly one mode under `mcp`:

{
  "mcp": {
    "tool_allowlist": ["get_nodes", "get_vms", "get_containers", "get_storage"]
  }
}

Alternatively, use `tool_denylist`, or the comma-separated environment variables `MCP_TOOL_ALLOWLIST` and `MCP_TOOL_DENYLIST`. Do not configure both modes. Environment selection replaces the file-level filtering mode. An empty allowlist exposes no tools; an empty denylist hides none. Exact lowercase tool names are required, and unknown names fail startup so a typo cannot silently widen access. Restart or reconnect the MCP server after changing the filter.

2. Choose One Runtime Path

| Path | Best for | Start command | Verify | | --- | --- | --- | --- | | MCP stdio from PyPI | Claude Desktop, Cursor, VS Code, Codex, local agents | `uvx proxmox-mcp-plus` | client lists `get_nodes`, `get_vms`, and job tools | | Native MCP HTTP from Docker | remote MCP clients that support Streamable HTTP | `docker compose --profile mcp-http up -d proxmox-mcp-http` | connect to `http://localhost:8000/mcp` | | OpenAPI bridge from Docker | HTTP clients, dashboards, scripts, no-code tools | `docker compose up -d` | `curl -f http://localhost:8811/livez` |

MCP stdio with PyPI

uvx proxmox-mcp-plus

Or install it first:

pip install proxmox-mcp-plus
proxmox-mcp-plus

Use this path when the MCP client launches a local stdio server.

Code Mode (opt-in)

Code Mode is disabled by default to preserve the legacy full tool catalog. Enable it with `mcp.code_mode: true` in the config file or `MCP_CODE_MODE=true`. When enabled, MCP exposes three tools instead: `proxmox_code_search`, `proxmox_code_get_schema`, and `proxmox_code_execute`. Code execution runs in an isolated sandbox and reaches domain tools through the existing validation, policy, and approval path. Discovery uses the filtered runtime catalog, so it also works in installed wheels. For example:

await call_tool("get_nodes", {"target": "default"})

The final expression is returned as `data.result`; tool results use MCP JSON content blocks (and structured content where supplied). Use `proxmox_code_get_schema` for arguments, including `target` and approval tokens. Scripts have no filesystem or network access except registered tool calls. Limits: 64,000 source characters, 100 MB sandbox memory, 25 tool calls, 16 KB final JSON, and two concurrent executions. Execution has a 30-second budget; cancelling or failing a script does not roll back tool side effects. Do not automatically retry a failed mutation script.

Optional worker reuse: set `mcp.code_mode_pool_reuse: true` or `MCP_CODE_MODE_POOL_REUSE=true`. The default remains one fresh worker per execution. Reuse keeps up to two workers for the server lifetime, recycles each after 100

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 · 688 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. # ProxmoxMCP-Plus
  2. <!-- mcp-name: io.github.RekklesNA/proxmox-mcp-plus -->
  3. <div align="center">
  4. <img src="docs/assets/logo-proxmoxmcp-plus.png" alt="ProxmoxMCP-Plus Logo" width="160"/>
  5. </div>
  6. <p align="center"><strong>Operate Proxmox VE from MCP clients, AI agents, and OpenAPI tooling through one security-conscious control plane for VMs, LXCs, snapshots, backups, ISOs, container commands, and persistent long-running jobs.</strong></p>
  7. <p align="center">
  8. <a href="https://pypi.org/project/proxmox-mcp-plus/"><img alt="PyPI" src="https://img.shields.io/pypi/v/proxmox-mcp-plus"></a>
  9. <a href="https://github.com/RekklesNA/ProxmoxMCP-Plus/releases"><img alt="GitHub Release" src="https://img.shields.io/github/v/release/RekklesNA/ProxmoxMCP-Plus"></a>
  10. <a href="https://github.com/RekklesNA/ProxmoxMCP-Plus/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/RekklesNA/ProxmoxMCP-Plus/ci.yml?branch=main"></a>
  11. <a href="https://github.com/RekklesNA/ProxmoxMCP-Plus/pkgs/container/ProxmoxMCP-Plus"><img alt="GHCR" src="https://img.shields.io/badge/GHCR-container-blue"></a>
  12. <a href="LICENSE"><img alt="License" src="https://img.shields.io/github/license/RekklesNA/ProxmoxMCP-Plus"></a>
  13. </p>
  14. <p align="center">
  15. <a href="#quick-start">Quick Start</a> |
  16. <a href="#client-install">Client Install</a> |
  17. <a href="#demo">Demo</a> |
  18. <a href="#choose-the-right-tool">Tools</a> |
  19. <a href="#safety-model">Safety</a> |
  20. <a href="#scenario-templates">Scenarios</a> |
  21. <a href="#documentation">Docs</a> |
  22. <a href="https://github.com/RekklesNA/ProxmoxMCP-Plus/wiki">Wiki</a>
  23. </p>
  24. [![Architecture: MCP and OpenAPI entry points, guarded target-aware tools, Proxmox VE, and persistent jobs](docs/assets/proxmoxmcp-nature-architecture.svg)](docs/assets/proxmoxmcp-nature-architecture.svg)
  25. MCP and OpenAPI are alternative entry points into the same workflows and may
  26. run in separate processes. Solid arrows show requests and execution; dashed arrows
  27. show persisted job and audit state. Approval gates, SSH execution and MCP HTTP
  28. OAuth depend on configuration. Select the diagram to view it at full size.
  29. ## Why ProxmoxMCP-Plus
  30. ProxmoxMCP-Plus sits between AI clients and Proxmox VE so operators do not have to stitch together raw API calls, one-off shell scripts, and custom job polling for every workflow.
  31. It exposes the same operational surface in two ways:
  32. - `MCP` for Claude Desktop, Cursor, VS Code, Open WebUI, Codex, and other MCP-capable agents
  33. - `OpenAPI` for HTTP automation, dashboards, internal tools, and no-code workflows
  34. What you get:
  35. - VM and LXC lifecycle actions
  36. - snapshot create, rollback, and delete
  37. - backup and restore workflows
  38. - ISO download and cleanup
  39. - node, storage, and cluster inspection
  40. - SSH-backed container command execution with guardrails
  41. - opt-in guarded [Proxmox node SSH commands](docs/node-command-execution.md)
  42. - persistent job tracking for async Proxmox tasks
  43. ## What Makes It Different
  44. | Priority | How the project handles it |
  45. | --- | --- |
  46. | Dual access paths | Native MCP for agent workflows and OpenAPI for standard HTTP automation |
  47. | Proxmox-oriented workflows | Day-2 VM, LXC, snapshot, backup, ISO, storage, and cluster operations |
  48. | Long-running operations | Stable `job_id`s, Proxmox `UPID` tracking, polling, retry, cancel, and audit history |
  49. | Safer execution | Proxmox API tokens, OpenAPI bearer auth, command policy, approval tokens, TLS validation, and MCP HTTP Host/Origin controls |
  50. | Real validation | Unit, integration, Docker/OpenAPI, and live Proxmox e2e entry points are documented in the repo |
  51. ## Quick Start
  52. ### 1. Prepare Proxmox Credentials
  53. Create a Proxmox API token with only the permissions your workflows need. Then create the local config file:
  54. ```bash
  55. cp proxmox-config/config.example.json proxmox-config/config.json
  56. ```
  57. Then edit `proxmox-config/config.json` with your environment. At minimum, it needs:
  58. - `proxmox.host`
  59. - `proxmox.port`
  60. - `auth.user`
  61. - `auth.token_name`
  62. - `auth.token_value`
  63. Add an `ssh` section as well if you want container command execution.
  64. Add a `jobs` section if you want job state persisted somewhere other than the default local SQLite file.
  65. For real live verification, use a separate `proxmox-config/config.live.json` created from `proxmox-config/config.live.example.json`.
  66. Do not point live e2e at a placeholder or local-only `config.json` unless you intentionally run a local API tunnel there.
  67. Optional job persistence config:
  68. ```json
  69. {
  70. "jobs": {
  71. "sqlite_path": "proxmox-jobs.sqlite3"
  72. }
  73. }
  74. ```
  75. Optional tool exposure filtering can reduce the schemas sent to MCP clients. It is
  76. disabled by default, so existing configurations continue to expose every available
  77. tool. Configure exactly one mode under `mcp`:
  78. ```json
  79. {
  80. "mcp": {
  81. "tool_allowlist": ["get_nodes", "get_vms", "get_containers", "get_storage"]
  82. }
  83. }
  84. ```
  85. Alternatively, use `tool_denylist`, or the comma-separated environment variables
  86. `MCP_TOOL_ALLOWLIST` and `MCP_TOOL_DENYLIST`. Do not configure both modes. Environment
  87. selection replaces the file-level filtering mode. An empty allowlist exposes no tools;
  88. an empty denylist hides none. Exact lowercase tool names are required, and unknown names
  89. fail startup so a typo cannot silently widen access. Restart or reconnect the MCP server
  90. after changing the filter.
  91. ### 2. Choose One Runtime Path
  92. | Path | Best for | Start command | Verify |
  93. | --- | --- | --- | --- |
  94. | MCP stdio from PyPI | Claude Desktop, Cursor, VS Code, Codex, local agents | `uvx proxmox-mcp-plus` | client lists `get_nodes`, `get_vms`, and job tools |
  95. | Native MCP HTTP from Docker | remote MCP clients that support Streamable HTTP | `docker compose --profile mcp-http up -d proxmox-mcp-http` | connect to `http://localhost:8000/mcp` |
  96. | OpenAPI bridge from Docker | HTTP clients, dashboards, scripts, no-code tools | `docker compose --profile openapi up -d proxmox-mcp-api` | `curl -f http://localhost:8811/livez` |
  97. Docker examples publish host ports on `127.0.0.1` by default; Compose modes are opt-in. Set
  98. only the selected mode's key: `MCP_API_KEY` for native HTTP or `PROXMOX_API_KEY`
  99. for OpenAPI. See [Compose deployment and upgrade notes](docs/docker-compose.md)
  100. for reverse proxies, tunnels, explicit LAN bindings and container recreation.
  101. #### MCP stdio with PyPI
  102. ```bash
  103. uvx proxmox-mcp-plus
  104. ```
  105. Or install it first:
  106. ```bash
  107. pip install proxmox-mcp-plus
  108. proxmox-mcp-plus
  109. ```
  110. Use this path when the MCP client launches a local stdio server.
  111. #### Code Mode (opt-in)
  112. Code Mode is disabled by default to preserve the legacy full tool catalog. Enable it
  113. with `mcp.code_mode: true` in the config file or `MCP_CODE_MODE=true`. When enabled,
  114. MCP exposes three tools instead: `proxmox_code_search`, `proxmox_code_get_schema`, and
  115. `proxmox_code_execute`. Code execution runs in an isolated sandbox and reaches domain
  116. tools through the existing validation, policy, and approval path. Discovery uses the
  117. filtered runtime catalog, so it also works in installed wheels. For example:
  118. ```python
  119. await call_tool("get_nodes", {"target": "default"})
  120. ```
  121. The final expression is returned as `data.result`; tool results use MCP JSON content
  122. blocks (and structured content where supplied). Use `proxmox_code_get_schema` for
  123. arguments, including `target` and approval tokens. Scripts have no filesystem or
  124. network access except registered tool calls. Limits: 64,000 source characters,
  125. 100 MB sandbox memory, 25 tool calls, 16 KB final JSON, and two concurrent executions.
  126. Execution has a 30-second budget; cancelling or failing a script does not roll back
  127. tool side effects. Do not automatically retry a failed mutation script.
  128. Optional worker reuse: set `mcp.code_mode_pool_reuse: true` or
  129. `MCP_CODE_MODE_POOL_REUSE=true`. The default remains one fresh worker per execution.
  130. Reuse keeps up to two workers for the server lifetime, recycles each after 100
  131. checkouts, and starts a new sandbox session per request. Globals, approvals, output
  132. collectors and call limits are not shared between requests. HTTP clients share the
  133. server-owned pool; disconnecting a client does not close it. Run
  134. `python scripts/benchmark_code_mode.py` to measure local startup overhead; this is
  135. a microbenchmark, not an estimate of Proxmox operation latency.
  136. #### Native MCP HTTP with Docker
  137. Use this path when a remote MCP client supports Streamable HTTP:
  138. ```bash
  139. export MCP_API_KEY="$(openssl rand -hex 32)"
  140. docker run --rm -p 127.0.0.1:8000:8000 \
  141. -e PROXMOX_MCP_MODE=mcp-http \
  142. -e MCP_HOST=0.0.0.0 \
  143. -e MCP_PORT=8000 \
  144. -e MCP_TRANSPORT=STREAMABLE_HTTP \
  145. -e MCP_API_KEY="$MCP_API_KEY" \
  146. -v "$(pwd)/proxmox-config/config.json:/app/proxmox-config/config.json:ro" \
  147. ghcr.io/rekklesna/proxmoxmcp-plus:latest
  148. ```
  149. Point MCP clients at:
  150. ```text
  151. http://127.0.0.1:8000/mcp
  152. ```
  153. For remote clients, use the configured proxy/tunnel URL or explicitly widen the host binding as described in [Docker deployment](docs/docker-compose.md).
  154. Send `Authorization: Bearer <MCP_API_KEY>` with every native MCP HTTP request.
  155. The key is independent of Proxmox credentials. Native Streamable HTTP and SSE
  156. require a key by default. For an endpoint protected by an external access-control
  157. layer such as Tailscale ACLs, explicitly set `MCP_ALLOW_UNAUTHENTICATED_HTTP=true`
  158. or `mcp.allow_unauthenticated_http: true` in JSON configuration. This allows
  159. keyless startup and logs a warning; it does not configure or verify the external
  160. access controls. A configured `MCP_API_KEY` is always enforced, even with opt-out.
  161. This setting does not change OpenAPI authentication or DNS rebinding protection.
  162. ##### OAuth browser gate for MCP clients
  163. Native MCP HTTP can optionally expose an OAuth authorization-code flow with PKCE
  164. while keeping `MCP_API_KEY` as the only human credential an operator has to
  165. manage. OAuth protocol handling is delegated to the MCP Python SDK
  166. (`mcp>=1.30.0,<2`), while ProxmoxMCP-Plus provides the API-key consent policy
  167. and persistent OAuth state.
  168. OAuth state is stored in PostgreSQL. This allows multiple MCP server instances or
  169. hosts, when deployed explicitly, to share registered clients, authorization codes,
  170. access tokens, refresh tokens, refresh-token replay protection, and login-rate-limit
  171. state without relying on a local filesystem.
  172. The client starts at the SDK `/authorize` endpoint. After the SDK validates the
  173. client, redirect URI, scope, PKCE request, and resource, the browser is redirected
  174. to `/oauth/consent` on the same MCP origin. The user reviews the client name,
  175. redirect origin, and requested scopes, then enters `MCP_API_KEY`. The API key is
  176. never placed in a URL and is never returned to the OAuth client.
  177. Required OAuth settings:
  178. ```bash
  179. export MCP_API_KEY="$(openssl rand -hex 32)"
  180. # Replace <password> with the database user's password.
  181. export MCP_OAUTH_DATABASE_URL='postgresql://proxmox_oauth:<password>@postgres.example:5432/proxmox_oauth'
  182. ```
  183. Example server:
  184. ```bash
  185. docker run --rm -p 127.0.0.1:8000:8000 \
  186. -e PROXMOX_MCP_MODE=mcp-http \
  187. -e MCP_HOST=0.0.0.0 \
  188. -e MCP_PORT=8000 \
  189. -e MCP_TRANSPORT=STREAMABLE_HTTP \
  190. -e MCP_API_KEY="$MCP_API_KEY" \
  191. -e MCP_OAUTH_ENABLED=true \
  192. -e MCP_OAUTH_ISSUER=https://mcp.example.com \
  193. -e MCP_OAUTH_DATABASE_URL="$MCP_OAUTH_DATABASE_URL" \
  194. -e MCP_ALLOWED_HOSTS=mcp.example.com:*,localhost:* \
  195. -e MCP_ALLOWED_ORIGINS=https://mcp.example.com \
  196. -v "$(pwd)/proxmox-config/config.json:/app/proxmox-config/config.json:ro" \
  197. ghcr.io/rekklesna/proxmoxmcp-plus:latest
  198. ```
  199. Then connect the OAuth-capable client to:
  200. ```text
  201. https://mcp.example.com/mcp
  202. ```
  203. OAuth mode exposes these endpoints on the same public origin:
  204. - `/.well-known/oauth-protected-resource/mcp` - RFC 9728 protected-resource metadata
  205. - `/.well-known/oauth-authorization-server` - SDK authorization-server metadata
  206. - `/register` - SDK dynamic client registration (DCR)
  207. - `/authorize` - SDK authorization endpoint
  208. - `/token` - SDK authorization-code/refresh-token exchange
  209. - `/oauth/consent` - ProxmoxMCP-Plus API-key consent page
  210. The SDK requires PKCE `S256` and protects the MCP resource with issued OAuth
  211. access tokens. Browser consent transactions are short-lived, HMAC-signed, and
  212. stateless. All durable OAuth state is stored in PostgreSQL.
  213. Authorization-code consumption and refresh-token rotation use PostgreSQL
  214. transactions. A code or refresh token is deleted and its replacement tokens are
  215. inserted atomically, so concurrent server instances cannot successfully replay the
  216. same credential. Dynamic client registration capacity is also serialized with a
  217. PostgreSQL transaction-scoped advisory lock; inactive registrations are pruned
  218. before the configured limit is exceeded.
  219. `MCP_API_KEY` is the sole source of truth for the browser consent credential.
  220. This runtime does not persist the key or its verifier in PostgreSQL. The server process
  221. validates consent directly against the value supplied in its environment. If the
  222. service is explicitly deployed as multiple containers or instances, configure the
  223. same secret for each instance. Stop all instances before changing the key, then
  224. restart/recreate all of them with the new value before routing traffic again.
  225. Existing OAuth clients and issued tokens are independent of the browser-gate key
  226. and remain valid until they expire or are revoked.
  227. Required when OAuth is enabled:
  228. | Variable | Purpose |
  229. | --- | --- |
  230. | `MCP_API_KEY` | Human credential entered only on the consent page |
  231. | `MCP_OAUTH_ISSUER` | Public HTTPS origin of this MCP authorization server |
  232. | `MCP_OAUTH_DATABASE_URL` | PostgreSQL DSN used for OAuth state |
  233. Optional OAuth environment variables:
  234. | Variable | Default | Purpose |
  235. | --- | --- | --- |
  236. | `MCP_OAUTH_RESOURCE` | `<issuer>/mcp` | Public MCP resource identifier; must use the issuer origin |
  237. | `MCP_OAUTH_SCOPES` | `mcp` | Comma-separated required scopes |
  238. | `MCP_OAUTH_ACCESS_TOKEN_TTL_SECONDS` | `3600` | Access-token lifetime |
  239. | `MCP_OAUTH_REFRESH_TOKEN_TTL_SECONDS` | `2592000` | Refresh-token lifetime (30 days) |
  240. | `MCP_OAUTH_MAX_REGISTERED_CLIENTS` | `4096` | Maximum persisted DCR clients before inactive-client pruning |
  241. | `MCP_OAUTH_DB_POOL_MIN_SIZE` | `1` | Minimum asyncpg connections per MCP process |
  242. | `MCP_OAUTH_DB_POOL_MAX_SIZE` | `10` | Maximum asyncpg connections per MCP process |
  243. | `MCP_OAUTH_DB_COMMAND_TIMEOUT_SECONDS` | `10` | PostgreSQL command timeout used by the OAuth store |
  244. | `MCP_OAUTH_CLIENT_IP_HEADER` | unset | Trusted reverse-proxy header used only for login rate limiting |
  245. To rotate the browser-gate credential, stop every MCP instance using this issuer,
  246. update `MCP_API_KEY` in the deployment environment, and restart/recreate all
  247. instances with the same new key. The environment is read when the provider starts;
  248. editing a running container's environment does not reload its key. No OAuth
  249. database metadata or key-version update is required. Pending consent transactions
  250. created with the previous key will no longer validate after every instance has
  251. restarted; already issued OAuth tokens remain governed by their normal lifetime
  252. and revocation rules. A rolling key change leaves old instances accepting the old
  253. key and causes consent requests routed between different-key instances to fail.
  254. There is no database guard to detect or disable a stale instance. Changing the
  255. browser-gate key does not revoke existing access tokens, refresh tokens, or
  256. authorization codes; use explicit revocation for compromised OAuth credentials.
  257. When upgrading from an OAuth build that used `MCP_OAUTH_KEY_VERSION`, startup
  258. ignores the old variable and leaves `proxmox_mcp_oauth_metadata` untouched. Fresh
  259. databases do not create that table. Registered clients and issued OAuth credentials
  260. are preserved; no manual SQL migration is required. Keeping legacy metadata avoids
  261. breaking old workers' queries and permits rollback with the same API key and
  262. legacy key version. Back up the database before upgrading and stop all old
  263. instances before rotating the key. After a key change, the legacy metadata still
  264. describes the old key: rollback requires restoring the old configuration or
  265. following the old version's rotation procedure, which invalidates OAuth state.
  266. Only remove the legacy table manually once all old instances are retired and a
  267. rollback is no longer needed; it can still contain the previous key's verifier.
  268. The database role must be able to create and modify the
  269. `proxmox_mcp_oauth_*` tables in its database. The tables contain OAuth client
  270. metadata, including issued client secrets, plus authorization codes and active
  271. tokens, so the PostgreSQL database and backups must be protected as credential
  272. storage.
  273. If several MCP instances use the same `MCP_OAUTH_DATABASE_URL`, OAuth state and
  274. one-time-token enforcement are shared across them. Size the database capacity with
  275. the total number of MCP processes in mind because the configured pool limits apply
  276. per process.
  277. If the server is behind a trusted reverse proxy and per-user login rate limiting
  278. must use the original client address, set `MCP_OAUTH_CLIENT_IP_HEADER` to a header
  279. that the proxy overwrites (for example `CF-Connecting-IP`). Leave it unset unless
  280. the proxy prevents clients from spoofing that header.
  281. When `MCP_OAUTH_ENABLED=true`, a raw `Authorization: Bearer <MCP_API_KEY>`
  282. request to `/mcp` is intentionally rejected. The API key is accepted only by the
  283. consent page; MCP requests must use an issued OAuth access token.
  284. When serving MCP HTTP behind a reverse proxy, keep DNS rebinding protection
  285. enabled and allow only the hostnames you expect.
  286. #### OpenAPI bridge with Docker
  287. OpenAPI mode is the default Docker runtime and requires an API key:
  288. ```bash
  289. export PROXMOX_API_KEY="$(openssl rand -hex 32)"
  290. docker run --rm -p 127.0.0.1:8811:8811 \
  291. -e PROXMOX_API_KEY="$PROXMOX_API_KEY" \
  292. -v "$(pwd)/proxmox-config/config.json:/app/proxmox-config/config.json:ro" \
  293. ghcr.io/rekklesna/proxmoxmcp-plus:latest
  294. ```
  295. Verify the OpenAPI surface:
  296. ```bash
  297. curl -f http://localhost:8811/livez
  298. curl -f -H "Authorization: Bearer $PROXMOX_API_KEY" http://localhost:8811/health
  299. curl -H "Authorization: Bearer $PROXMOX_API_KEY" http://localhost:8811/openapi.json
  300. ```
  301. For local unauthenticated development only, set `PROXMOX_ALLOW_NO_AUTH=true`.
  302. #### Source checkout
  303. ```bash
  304. git clone https://github.com/RekklesNA/ProxmoxMCP-Plus.git
  305. cd ProxmoxMCP-Plus
  306. uv venv
  307. uv pip install -e ".[dev]"
  308. python main.py
  309. ```
  310. The `8811` service is the OpenAPI/REST bridge. The `8000` service is the native MCP HTTP endpoint.
  311. ## Client Install
  312. Use the one-click buttons when your client supports MCP install deeplinks, or copy the JSON config below.
  313. [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=proxmox-mcp-plus&inputs=%5B%7B%22id%22%3A%22proxmox_host%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Proxmox%20host%22%7D%2C%7B%22id%22%3A%22proxmox_user%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Proxmox%20user%2C%20for%20example%20root%40pam%22%7D%2C%7B%22id%22%3A%22proxmox_token_name%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Proxmox%20API%20token%20name%22%7D%2C%7B%22id%22%3A%22proxmox_token_value%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Proxmox%20API%20token%20value%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22proxmox-mcp-plus%22%5D%2C%22env%22%3A%7B%22PROXMOX_HOST%22%3A%22%24%7Binput%3Aproxmox_host%7D%22%2C%22PROXMOX_USER%22%3A%22%24%7Binput%3Aproxmox_user%7D%22%2C%22PROXMOX_TOKEN_NAME%22%3A%22%24%7Binput%3Aproxmox_token_name%7D%22%2C%22PROXMOX_TOKEN_VALUE%22%3A%22%24%7Binput%3Aproxmox_token_value%7D%22%2C%22PROXMOX_VERIFY_SSL%22%3A%22true%22%7D%7D)
  314. [![Install in Cursor](https://img.shields.io/badge/Cursor-Install_Server-000000?style=flat-square)](https://cursor.com/en/install-mcp?name=proxmox-mcp-plus&config=eyJjb21tYW5kIjoidXZ4IHByb3htb3gtbWNwLXBsdXMiLCJlbnYiOnsiUFJPWE1PWF9IT1NUIjoieW91ci1wcm94bW94LWhvc3QiLCJQUk9YTU9YX1VTRVIiOiJyb290QHBhbSIsIlBST1hNT1hfVE9LRU5fTkFNRSI6Im1jcC10b2tlbiIsIlBST1hNT1hfVE9LRU5fVkFMVUUiOiJ5b3VyLXRva2VuLXNlY3JldCIsIlBST1hNT1hfVkVSSUZZX1NTTCI6InRydWUifX0=)
  315. Recommended stdio config:
  316. ```json
  317. {
  318. "mcpServers": {
  319. "proxmox-mcp-plus": {
  320. "command": "uvx",
  321. "args": ["proxmox-mcp-plus"],
  322. "env": {
  323. "PROXMOX_HOST": "your-proxmox-host",
  324. "PROXMOX_USER": "root@pam",
  325. "PROXMOX_TOKEN_NAME": "mcp-token",
  326. "PROXMOX_TOKEN_VALUE": "your-token-secret",
  327. "PROXMOX_PORT": "8006",
  328. "PROXMOX_VERIFY_SSL": "true"
  329. }
  330. }
  331. }
  332. }
  333. ```
  334. Use a local config file if you prefer not to keep credentials in the client config:
  335. ```json
  336. {
  337. "mcpServers": {
  338. "proxmox-mcp-plus": {
  339. "command": "uvx",
  340. "args": ["proxmox-mcp-plus"],
  341. "env": {
  342. "PROXMOX_MCP_CONFIG": "/path/to/ProxmoxMCP-Plus/proxmox-config/config.json"
  343. }
  344. }
  345. }
  346. }
  347. ```
  348. Client-specific examples for Claude Desktop, Cursor, VS Code, Codex, OpenCode, Open WebUI, Streamable HTTP, and OpenAPI are in the [Client Setup Guide](docs/wiki/Client%20Setup.md) and [Integrations Guide](docs/wiki/Integrations%20Guide.md).
  349. ## Demo
  350. This demo is a direct terminal recording of `qwen/qwen3.6-plus` driving a live MCP session in English against a local Proxmox lab. It shows natural-language control flowing through MCP tools to create and start an LXC, execute a container command, and confirm the authenticated HTTP `/health` surface.
  351. ![Recorded demo gif](docs/assets/proxmoxmcp-demo.gif)
  352. [Watch the MP4 version](docs/assets/proxmoxmcp-demo.mp4)
  353. ## Choose The Right Tool
  354. Start with read-only discovery, then move to mutating tools only after the target node, storage, VMID, and permissions are clear.
  355. | Operator goal | Start with | Then use | Notes |
  356. | --- | --- | --- | --- |
  357. | Inspect the cluster | `get_nodes`, `get_cluster_status` | `get_storage`, `get_vms`, `get_containers` | Best first health check after client install |
  358. | Create or manage a VM | `get_nodes`, `get_storage` | `create_vm`, `start_vm`, `stop_vm`, `delete_vm` | Long-running mutations return `job_id` and Proxmox `task_id` |
  359. | Manage LXCs | `get_containers`, `get_storage` | `create_container`, `start_container`, `stop_container`, `delete_container` | SSH-backed command tools require the optional `ssh` config |
  360. | Roll back risky changes | `list_snapshots` with `vm_type=qemu` or `vm_type=lxc` | `create_snapshot`, `rollback_snapshot`, `delete_snapshot` | Create a snapshot before destructive workflow tests |
  361. | Run commands inside guests | VM or container status tools | `execute_vm_command`, `execute_container_command` | VM path needs QEMU Guest Agent; LXC path needs SSH to the Proxmox node |
  362. | Track async work | mutation response with `job_id` | `poll_job`, `get_job`, `list_jobs`, `retry_job`, `cancel_job` | Use `job_id` for agent/user conversations and `task_id` for raw Proxmox traceability |
  363. | Inspect logs | `get_node_syslog`, `get_cluster_log` | `get_task_log`, `get_node_firewall_log`, `get_guest_firewall_log` | All log tools are read-only; `get_task_log` accepts any Proxmox `UPID` |
  364. | Automate from HTTP tools | `/openapi.json` | `/jobs`, `/health`, generated tool routes | Use bearer auth and keep CORS restricted outside local development |
  365. For the full tool map, see the [Tool Selection Guide](docs/wiki/Tool%20Selection%20Guide.md) and [API & Tool Reference](docs/wiki/API%20%26%20Tool%20Reference.md).
  366. ## Safety Model
  367. ProxmoxMCP-Plus is an access layer, not a replacement for Proxmox RBAC, network controls, or client-side MCP approval prompts.
  368. The project gives operators several control points:
  369. - Proxmox API tokens decide what the backend can do.
  370. - `PROXMOX_API_KEY` protects the OpenAPI bridge by default.
  371. - `MCP_API_KEY` protects native Streamable HTTP and SSE with Bearer authentication; it is required unless `MCP_ALLOW_UNAUTHENTICATED_HTTP=true` explicitly delegates access control.
  372. - TLS verification is enforced unless development mode is explicitly enabled.
  373. - `command_policy` controls command execution and high-risk operations.
  374. - `approval_token` can gate command execution and high-risk mutating actions.
  375. - MCP Streamable HTTP deployments can use DNS rebinding protection plus Host and Origin allowlists.
  376. - Optional MCP tool allowlists or denylists reduce the runtime tool surface; they do not replace Proxmox RBAC.
  377. - Logs are designed to avoid exposing command and credential material.
  378. Read the [Security Guide](docs/wiki/Security%20Guide.md) before exposing the server outside a trusted local environment.
  379. ## Core Platform Capabilities
  380. ProxmoxMCP-Plus provides a unified control surface for the operational tasks most teams actually need in Proxmox VE. The same server can expose these workflows to MCP clients for LLM and AI-agent use cases, and to HTTP consumers through the OpenAPI bridge.
  381. Supported workflow areas:
  382. | Capability Area | Availability |
  383. | --- | --- |
  384. | VM create / start / stop / delete | Available |
  385. | VM snapshot create / rollback / delete | Available |
  386. | Backup create / restore | Available |
  387. | ISO download / delete | Available |
  388. | LXC create / start / stop / delete | Available |
  389. | Container SSH-backed command execution | Available |
  390. | Container authorized_keys update | Available |
  391. | Persistent job store for long tasks | Available |
  392. | MCP job control tools (`list_jobs`, `get_job`, `poll_job`, `cancel_job`, `retry_job`) | Available |
  393. | OpenAPI `/jobs` endpoints with explicit status codes | Available |
  394. | Local OpenAPI `/livez`, `/readyz`, `/health`, and schema | Available |
  395. | Docker native MCP Streamable HTTP at `/mcp` | Available |
  396. | Docker image build and `/livez` | Available |
  397. Validation and contract entry points in this repository:
  398. - `python -m pytest -q` (see [Contributing](CONTRIBUTING.md#validate-a-change) for the full CI coverage gate)
  399. - `ruff check .`
  400. - `mypy src --ignore-missing-imports`
  401. - `python -m pip_audit -r requirements/runtime.lock --require-hashes --disable-pip --strict`
  402. - `tests/integration/test_real_contract.py`
  403. - `tests/scripts/run_real_e2e.py`
  404. `tests/scripts/run_real_e2e.py` now prefers `proxmox-config/config.live.json` or `PROXMOX_MCP_E2E_CONFIG`.
  405. This avoids accidentally running live checks against a machine-specific default `config.json`.
  406. ## Long-Running Jobs
  407. Many Proxmox mutations are asynchronous. ProxmoxMCP-Plus now wraps those tasks in a persistent job layer so MCP and OpenAPI clients can track them through a stable `Job ID`.
  408. Long-running tools such as VM create/start/stop, container create/start/stop, snapshot changes, backup/restore, and ISO download/delete now return both:
  409. - `task_id`: the raw Proxmox `UPID`
  410. - `job_id`: the stable server-side job record
  411. The job record stores:
  412. - current status and progress
  413. - retry count and prior `UPID`s
  414. - latest result payload or failure reason
  415. - audit history for create, poll, retry, and cancel actions
  416. By default the job store persists to `proxmox-jobs.sqlite3`, so restart does not lose in-flight or completed job metadata.
  417. Audit events are appended to a separate SQLite table. Existing history is migrated
  418. on startup and the API's `audit_log` format stays unchanged. Retention is unlimited
  419. by default; set `jobs.audit_retention_days` to a positive number in JSON config to
  420. prune expired events at startup and when each job is updated. This never deletes
  421. the job itself. Stop all workers sharing the database and back it up before this
  422. upgrade. Do not run old and new versions against the same database; restore the
  423. pre-upgrade backup if downgrading and retaining audit history is required.
  424. A cancellation request is not completion. Poll until the task is failed/cancelled
  425. before calling `retry_job`; pending cancellation cannot be retried.
  426. ### MCP Job Tools
  427. - `list_jobs`
  428. - `get_job`
  429. - `poll_job`
  430. - `cancel_job`
  431. - `retry_job`
  432. ### OpenAPI Job Routes
  433. When the OpenAPI proxy is enabled and a local `JobStore` is available, these routes are exposed directly:
  434. | Path | Method | Purpose | Success Codes |
  435. | --- | --- | --- | --- |
  436. | `/jobs` | `GET` | list persisted jobs | `200` |
  437. | `/jobs/{job_id}` | `GET` | fetch one job, optional `refresh=true` | `200` |
  438. | `/jobs/{job_id}/poll` | `POST` | refresh status from Proxmox | `200` |
  439. | `/jobs/{job_id}/cancel` | `POST` | request cancellation | `202` |
  440. | `/jobs/{job_id}/retry` | `POST` | replay a stored retry recipe | `202` |
  441. Common error codes:
  442. - `404`: unknown `job_id`
  443. - `409`: the job exists but that operation is not valid now
  444. - `503`: the OpenAPI proxy was started without a local `JobStore`
  445. `tests/scripts/run_real_e2e.py` now prefers `proxmox-config/config.live.json` or `PROXMOX_MCP_E2E_CONFIG`.
  446. This avoids accidentally running live checks against a machine-specific default `config.json`.
  447. ## Positioning Against Common Approaches
  448. | Capability | Official Proxmox API | One-off scripts | ProxmoxMCP-Plus |
  449. | --- | --- | --- | --- |
  450. | MCP for LLM and AI agent workflows | No | No | Yes |
  451. | OpenAPI surface for standard HTTP tooling | No | Usually no | Yes |
  452. | VM and LXC operations in one interface | Low-level only | Depends | Yes |
  453. | Snapshot, backup, and restore workflows | Low-level only | Depends | Yes |
  454. | Persistent async job tracking and retry | No | Rare | Yes |
  455. | Container command execution with policy controls | No | Custom only | Yes |
  456. | Docker distribution path | No | Rare | Yes |
  457. | Repository-level live-environment verification | N/A | Rare | Yes |
  458. ## Scenario Templates
  459. Ready-to-copy examples live in [`docs/examples/`](docs/examples/README.md):
  460. - [Create a test VM](docs/examples/create-test-vm.md)
  461. - [Roll back a risky change with snapshots](docs/examples/rollback-snapshot.md)
  462. - [Download an ISO and create an LXC](docs/examples/download-iso-and-create-lxc.md)
  463. These are written for both human operators and LLM-driven usage.
  464. ## Documentation
  465. The README is intentionally optimized for fast GitHub comprehension. Longer operational docs live in `docs/wiki/` and can also be published to the GitHub Wiki.
  466. | If you need to... | Start here |
  467. | --- | --- |
  468. | Understand the project and deployment flow | [Wiki Home](docs/wiki/Home.md) |
  469. | Configure and run against a Proxmox environment | [Operator Guide](docs/wiki/Operator%20Guide.md) |
  470. | Connect Claude Desktop, Cursor, VS Code, Codex, Open WebUI, or HTTP clients | [Client Setup Guide](docs/wiki/Client%20Setup.md) |
  471. | Choose the right tool for a workflow | [Tool Selection Guide](docs/wiki/Tool%20Selection%20Guide.md) |
  472. | Review docs quality goals, media plan, and publishing checklist | [Documentation Quality Plan](docs/wiki/Documentation%20Quality%20Plan.md) |
  473. | Review integration patterns and transport details | [Integrations Guide](docs/wiki/Integrations%20Guide.md) |
  474. | Install from MCP-aware IDEs and agents | [Agent Installation](docs/agent-installation.md) |
  475. | Enable LXC command execution over SSH | [Container Command Execution](docs/container-command-execution.md) |
  476. | Review security and command policy | [Security Guide](docs/wiki/Security%20Guide.md) |
  477. | Inspect tool parameters, prerequisites, and behavior | [API & Tool Reference](docs/wiki/API%20%26%20Tool%20Reference.md) |
  478. | Debug startup, auth, or health issues | [Troubleshooting](docs/wiki/Troubleshooting.md) |
  479. | Work on the codebase or release it | [Developer Guide](docs/wiki/Developer%20Guide.md) |
  480. | Review release and upgrade notes | [Release & Upgrade Notes](docs/wiki/Release%20%26%20Upgrade%20Notes.md) |
  481. Published wiki:
  482. - [GitHub Wiki Home](https://github.com/RekklesNA/ProxmoxMCP-Plus/wiki/Home)
  483. ## Repo Layout
  484. - `src/proxmox_mcp/`: MCP server, config loading, security, OpenAPI bridge
  485. - `main.py`: MCP entrypoint for local and client-driven usage
  486. - `docker-compose.yml`: HTTP/OpenAPI runtime
  487. - `requirements/`: auxiliary dependency sources and runtime install lists
  488. - `scripts/`: helper startup scripts for local workflows
  489. - `tests/scripts/run_real_e2e.py`: live Proxmox and Docker/OpenAPI path
  490. - `tests/`: unit and integration coverage
  491. - `docs/examples/`: scenario-driven prompts and HTTP examples
  492. - `docs/wiki/`: longer-form operator, integration, and reference docs
  493. ## Development Checks
  494. See [Contributing](CONTRIBUTING.md) for environment setup, test prerequisites,
  495. and pull request guidance.
  496. ```bash
  497. python -m pytest -q
  498. ruff check .
  499. mypy src --ignore-missing-imports
  500. python -m pip_audit -r requirements/runtime.lock --require-hashes --disable-pip --strict
  501. python -m build
  502. ```
  503. CI also runs PostgreSQL-backed tests and enforces full runtime statement coverage
  504. and full branch coverage for critical modules. See [Contributing](CONTRIBUTING.md#validate-a-change)
  505. for the exact coverage commands and [Dependency updates](docs/dependency-updates.md)
  506. for the reviewed runtime lock workflow.
  507. ## Community
  508. - [Contributing](CONTRIBUTING.md)
  509. - [Code of Conduct](CODE_OF_CONDUCT.md)
  510. - [Accessibility](ACCESSIBILITY.md)
  511. - [Security Policy](.github/SECURITY.md)
  512. - [Report an issue](https://github.com/RekklesNA/ProxmoxMCP-Plus/issues/new/choose)
  513. - [Discussions](https://github.com/RekklesNA/ProxmoxMCP-Plus/discussions)
  514. ## License
  515. [MIT](LICENSE)
  516. ### ISO installation and LXC network configuration
  517. Use `list_isos` to find an existing ISO volume (or `download_iso` to obtain one).
  518. `create_vm` accepts `iso_volume="local:iso/debian.iso"`, mounts it on `ide3` by
  519. default and boots CD-ROM before disk. `update_vm_config` can mount or change that
  520. ISO, eject with `iso_volume="none"`, set `boot_order="scsi0;ide3"`, or change
  521. `network_bridge` on `net0` while retaining MAC/VLAN/firewall settings. Choose a
  522. free `cdrom_device`; existing data disks and cloud-init drives are never replaced.
  523. Media and bridge edits read current configuration and therefore need `VM.Audit`
  524. as well as the relevant configuration privileges. Existing sizing/cloud-init-only
  525. updates still do not require a preliminary read.
  526. LXC uses OS templates, not installer ISOs. `create_container` retains DHCP by default
  527. and now accepts `network_bridge`, `ip="192.168.1.50/24"`, `gw="192.168.1.1"`, `ip6`
  528. and `gw6`. `update_container_network` edits those fields on an existing interface
  529. (default `net0`, selectable through `net31`) and preserves all unspecified options.
  530. Use an empty gateway string to remove it; changing to DHCP/manual removes the old
  531. gateway for that address family. Network changes can interrupt guest connectivity.
  532. Both edit tools follow named-target, read-only and high-risk approval policies.
  533. Add `update_container_network` to custom high-risk lists and desired tool allowlists.
  534. See [v0.5.19 release notes](docs/releases/v0.5.19.md) for upgrade details.

Ratings and comments

Sign in to rate this skill.

Sign in

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