ProxmoxMCP-Plus

# ProxmoxMCP-Plus <!-- mcp-name: io.github.RekklesNA/proxmox-mcp-plus --> <div align="center"> <img src="docs/assets/logo-proxmoxmcp-plus.png" alt="ProxmoxMCP-Plus Logo" width="160"/> </div> <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> <p align="center"> <a href="https://pypi.org/project/proxmox-mcp-plus/"><img alt="PyPI" src="https://img.shields.io/pypi/v/proxmox-mcp-plus"></a> <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> <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> <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> <a href="LICENSE"><img alt="License" src="https://img.shields.io/github/license/RekklesNA/ProxmoxMCP-Plus"></a> </p> <p align="center"> <a href="#quick-start">Quick Start</a> | <a href="#client-install">Client Install</a> | <a href="#demo">Demo</a> | <a href="#choose-the-right-tool">Tools</a> | <a href="#safety-model">Safety</a> | <a href="#scenario-templates">Scenarios</a> | <a href="#documentation">Docs</a> | <a href="https://github.com/RekklesNA/ProxmoxMCP-Plus/wiki">Wiki</a> </p>  ## Why ProxmoxMCP-Plus 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. It exposes the same operational surface in two ways: - `MCP` for Claude Desktop, Cursor, VS Code, Open WebUI, Codex, and other MCP-capable agents - `OpenAPI` for HTTP automation, dashboards, internal tools, and no-code workflows What you get: - VM and LXC lifecycle actions - snapshot create, rollback, and delete - backup and restore workflows - ISO download and cleanup - node, storage, and cluster inspection - SSH-backed container command execution with guardrails - persistent job tracking for async Proxmox tasks ## What Makes It Different | Priority | How the project handles it | | --- | --- | | Dual access paths | Native MCP for agent workflows and OpenAPI for standard HTTP automation | | Proxmox-oriented workflows | Day-2 VM, LXC, snapshot, backup, ISO, storage, and cluster operations | | Long-running operations | Stable `job_id`s, Proxmox `UPID` tracking, polling, retry, cancel, and audit history | | Safer execution | Proxmox API tokens, OpenAPI bearer auth, command policy, approval tokens, TLS validation, and MCP HTTP Host/Origin controls | | Real validation | Unit, integration, Docker/OpenAPI, and live Proxmox e2e entry points are documented in the repo | ## Quick Start ### 1. Prepare Proxmox Credentials Create a Proxmox API token with only the permissions your workflows need. Then create the local config file: ```bash 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: ```json { "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`: ```json { "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 ```bash uvx proxmox-mcp-plus ``` Or install it first: ```bash 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: ```python 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 checkouts, and starts a new sandbox session per request. Globals, approvals, output collectors and call limits are not shared between requests. HTTP clients share the server-owned pool; disconnecting a client does not close it. Run `python scripts/benchmark_code_mode.py` to measure local startup overhead; this is a microbenchmark, not an estimate of Proxmox operation latency. #### Native MCP HTTP with Docker Use this path when a remote MCP client supports Streamable HTTP: ```bash export MCP_API_KEY="$(openssl rand -hex 32)" docker run --rm -p 8000:8000 \ -e PROXMOX_MCP_MODE=mcp-http \ -e MCP_HOST=0.0.0.0 \ -e MCP_PORT=8000 \ -e MCP_TRANSPORT=STREAMABLE_HTTP \ -e MCP_API_KEY="$MCP_API_KEY" \ -v "$(pwd)/proxmox-config/config.json:/app/proxmox-config/config.json:ro" \ ghcr.io/rekklesna/proxmoxmcp-plus:latest ``` Point MCP clients at: ```text http://<docker-host>:8000/mcp ``` Send `Authorization: Bearer <MCP_API_KEY>` with every native MCP HTTP request. The key is independent of Proxmox credentials. Native Streamable HTTP and SSE require a key by default. For an endpoint protected by an external access-control layer such as Tailscale ACLs, explicitly set `MCP_ALLOW_UNAUTHENTICATED_HTTP=true` or `mcp.allow_unauthenticated_http: true` in JSON configuration. This allows keyless startup and logs a warning; it does not configure or verify the external access controls. A configured `MCP_API_KEY` is always enforced, even with opt-out. This setting does not change OpenAPI authentication or DNS rebinding protection. ##### OAuth browser gate for MCP clients Native MCP HTTP can optionally expose an OAuth authorization-code flow with PKCE while keeping `MCP_API_KEY` as the only human credential an operator has to manage. OAuth protocol handling is delegated to the MCP Python SDK (`mcp>=1.30.0,<2`), while ProxmoxMCP-Plus provides the API-key consent policy and persistent OAuth state. OAuth state is stored in PostgreSQL. This allows multiple MCP server instances or hosts, when deployed explicitly, to share registered clients, authorization codes, access tokens, refresh tokens, refresh-token replay protection, and login-rate-limit state without relying on a local filesystem. The client starts at the SDK `/authorize` endpoint. After the SDK validates the client, redirect URI, scope, PKCE request, and resource, the browser is redirected to `/oauth/consent` on the same MCP origin. The user reviews the client name, redirect origin, and requested scopes, then enters `MCP_API_KEY`. The API key is never placed in a URL and is never returned to the OAuth client. Required OAuth settings: ```bash export MCP_API_KEY="$(openssl rand -hex 32)" export MCP_OAUTH_DATABASE_URL='postgresql://proxmox_oauth:secret@postgres.example:5432/proxmox_oauth' ``` Example server: ```bash docker run --rm -p 8000:8000 \ -e PROXMOX_MCP_MODE=mcp-http \ -e MCP_HOST=0.0.0.0 \ -e MCP_PORT=8000 \ -e MCP_TRANSPORT=STREAMABLE_HTTP \ -e MCP_API_KEY="$MCP_API_KEY" \ -e MCP_OAUTH_ENABLED=true \ -e MCP_OAUTH_ISSUER=https://mcp.example.com \ -e MCP_OAUTH_DATABASE_URL="$MCP_OAUTH_DATABASE_URL" \ -e MCP_ALLOWED_HOSTS=mcp.example.com:*,localhost:* \ -e MCP_ALLOWED_ORIGINS=https://mcp.example.com \ -v "$(pwd)/proxmox-config/config.json:/app/proxmox-config/config.json:ro" \ ghcr.io/rekklesna/proxmoxmcp-plus:latest ``` Then connect the OAuth-capable client to: ```text https://mcp.example.com/mcp ``` OAuth mode exposes these endpoints on the same public origin: - `/.well-known/oauth-protected-resource/mcp` - RFC 9728 protected-resource metadata - `/.well-known/oauth-authorization-server` - SDK authorization-server metadata - `/register` - SDK dynamic client registration (DCR) - `/authorize` - SDK authorization endpoint - `/token` - SDK authorization-code/refresh-token exchange - `/oauth/consent` - ProxmoxMCP-Plus API-key consent page The SDK requires PKCE `S256` and protects the MCP resource with issued OAuth access tokens. Browser consent transactions are short-lived, HMAC-signed, and stateless. All durable OAuth state is stored in PostgreSQL. Authorization-code consumption and refresh-token rotation use PostgreSQL transactions. A code or refresh token is deleted and its replacement tokens are inserted atomically, so concurrent server instances cannot successfully replay the same credential. Dynamic client registration capacity is also serialized with a PostgreSQL transaction-scoped advisory lock; inactive registrations are pruned before the configured limit is exceeded. `MCP_API_KEY` is the sole source of truth for the browser consent credential. This runtime does not persist the key or its verifier in PostgreSQL. The server process validates consent directly against the value supplied in its environment. If the service is explicitly deployed as multiple containers or instances, configure the same secret for each instance. Stop all instances before changing the key, then restart/recreate all of them with the new value before routing traffic again. Existing OAuth clients and issued tokens are independent of the browser-gate key and remain valid until they expire or are revoked. Required when OAuth is enabled: | Variable | Purpose | | --- | --- | | `MCP_API_KEY` | Human credential entered only on the consent page | | `MCP_OAUTH_ISSUER` | Public HTTPS origin of this MCP authorization server | | `MCP_OAUTH_DATABASE_URL` | PostgreSQL DSN used for OAuth state | Optional OAuth environment variables: | Variable | Default | Purpose | | --- | --- | --- | | `MCP_OAUTH_RESOURCE` | `<issuer>/mcp` | Public MCP resource identifier; must use the issuer origin | | `MCP_OAUTH_SCOPES` | `mcp` | Comma-separated required scopes | | `MCP_OAUTH_ACCESS_TOKEN_TTL_SECONDS` | `3600` | Access-token lifetime | | `MCP_OAUTH_REFRESH_TOKEN_TTL_SECONDS` | `2592000` | Refresh-token lifetime (30 days) | | `MCP_OAUTH_MAX_REGISTERED_CLIENTS` | `4096` | Maximum persisted DCR clients before inactive-client pruning | | `MCP_OAUTH_DB_POOL_MIN_SIZE` | `1` | Minimum asyncpg connections per MCP process | | `MCP_OAUTH_DB_POOL_MAX_SIZE` | `10` | Maximum asyncpg connections per MCP process | | `MCP_OAUTH_DB_COMMAND_TIMEOUT_SECONDS` | `10` | PostgreSQL command timeout used by the OAuth store | | `MCP_OAUTH_CLIENT_IP_HEADER` | unset | Trusted reverse-proxy header used only for login rate limiting | To rotate the browser-gate credential, stop every MCP instance using this issuer, update `MCP_API_KEY` in the deployment environment, and restart/recreate all instances with the same new key. The environment is read when the provider starts; editing a running container's environment does not reload its key. No OAuth database metadata or key-version update is required. Pending consent transactions created with the previous key will no longer validate after every instance has restarted; already issued OAuth tokens remain governed by their normal lifetime and revocation rules. A rolling key change leaves old instances accepting the old key and causes consent requests routed between different-key instances to fail. There is no database guard to detect or disable a stale instance. Changing the browser-gate key does not revoke existing access tokens, refresh tokens, or authorization codes; use explicit revocation for compromised OAuth credentials. When upgrading from an OAuth build that used `MCP_OAUTH_KEY_VERSION`, startup ignores the old variable and leaves `proxmox_mcp_oauth_metadata` untouched. Fresh databases do not create that table. Registered clients and issued OAuth credentials are preserved; no manual SQL migration is required. Keeping legacy metadata avoids breaking old workers' queries and permits rollback with the same API key and legacy key version. Back up the database before upgrading and stop all old instances before rotating the key. After a key change, the legacy metadata still describes the old key: rollback requires restoring the old configuration or following the old version's rotation procedure, which invalidates OAuth state. Only remove the legacy table manually once all old instances are retired and a rollback is no longer needed; it can still contain the previous key's verifier. The database role must be able to create and modify the `proxmox_mcp_oauth_*` tables in its database. The tables contain OAuth client metadata, including issued client secrets, plus authorization codes and active tokens, so the PostgreSQL database and backups must be protected as credential storage. If several MCP instances use the same `MCP_OAUTH_DATABASE_URL`, OAuth state and one-time-token enforcement are shared across them. Size the database capacity with the total number of MCP processes in mind because the configured pool limits apply per process. If the server is behind a trusted reverse proxy and per-user login rate limiting must use the original client address, set `MCP_OAUTH_CLIENT_IP_HEADER` to a header that the proxy overwrites (for example `CF-Connecting-IP`). Leave it unset unless the proxy prevents clients from spoofing that header. When `MCP_OAUTH_ENABLED=true`, a raw `Authorization: Bearer <MCP_API_KEY>` request to `/mcp` is intentionally rejected. The API key is accepted only by the consent page; MCP requests must use an issued OAuth access token. When serving MCP HTTP behind a reverse proxy, keep DNS rebinding protection enabled and allow only the hostnames you expect. #### OpenAPI bridge with Docker OpenAPI mode is the default Docker runtime and requires an API key: ```bash export PROXMOX_API_KEY="$(openssl rand -hex 32)" docker run --rm -p 8811:8811 \ -e PROXMOX_API_KEY="$PROXMOX_API_KEY" \ -v "$(pwd)/proxmox-config/config.json:/app/proxmox-config/config.json:ro" \ ghcr.io/rekklesna/proxmoxmcp-plus:latest ``` Verify the OpenAPI surface: ```bash curl -f http://localhost:8811/livez curl -f -H "Authorization: Bearer $PROXMOX_API_KEY" http://localhost:8811/health curl -H "Authorization: Bearer $PROXMOX_API_KEY" http://localhost:8811/openapi.json ``` For local unauthenticated development only, set `PROXMOX_ALLOW_NO_AUTH=true`. #### Source checkout ```bash git clone https://github.com/RekklesNA/ProxmoxMCP-Plus.git cd ProxmoxMCP-Plus uv venv uv pip install -e ".[dev]" python main.py ``` The `8811` service is the OpenAPI/REST bridge. The `8000` service is the native MCP HTTP endpoint. ## Client Install Use the one-click buttons when your client supports MCP install deeplinks, or copy the JSON config below. [](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) [](https://cursor.com/en/install-mcp?name=proxmox-mcp-plus&config=eyJjb21tYW5kIjoidXZ4IHByb3htb3gtbWNwLXBsdXMiLCJlbnYiOnsiUFJPWE1PWF9IT1NUIjoieW91ci1wcm94bW94LWhvc3QiLCJQUk9YTU9YX1VTRVIiOiJyb290QHBhbSIsIlBST1hNT1hfVE9LRU5fTkFNRSI6Im1jcC10b2tlbiIsIlBST1hNT1hfVE9LRU5fVkFMVUUiOiJ5b3VyLXRva2VuLXNlY3JldCIsIlBST1hNT1hfVkVSSUZZX1NTTCI6InRydWUifX0=) Recommended stdio config: ```json { "mcpServers": { "proxmox-mcp-plus": { "command": "uvx", "args": ["proxmox-mcp-plus"], "env": { "PROXMOX_HOST": "your-proxmox-host", "PROXMOX_USER": "root@pam", "PROXMOX_TOKEN_NAME": "mcp-token", "PROXMOX_TOKEN_VALUE": "your-token-secret", "PROXMOX_PORT": "8006", "PROXMOX_VERIFY_SSL": "true" } } } } ``` Use a local config file if you prefer not to keep credentials in the client config: ```json { "mcpServers": { "proxmox-mcp-plus": { "command": "uvx", "args": ["proxmox-mcp-plus"], "env": { "PROXMOX_MCP_CONFIG": "/path/to/ProxmoxMCP-Plus/proxmox-config/config.json" } } } } ``` 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). ## Demo 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.  [Watch the MP4 version](docs/assets/proxmoxmcp-demo.mp4) ## Choose The Right Tool Start with read-only discovery, then move to mutating tools only after the target node, storage, VMID, and permissions are clear. | Operator goal | Start with | Then use | Notes | | --- | --- | --- | --- | | Inspect the cluster | `get_nodes`, `get_cluster_status` | `get_storage`, `get_vms`, `get_containers` | Best first health check after client install | | 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` | | Manage LXCs | `get_containers`, `get_storage` | `create_container`, `start_container`, `stop_container`, `delete_container` | SSH-backed command tools require the optional `ssh` config | | 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 | | 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 | | 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 | | 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` | | Automate from HTTP tools | `/openapi.json` | `/jobs`, `/health`, generated tool routes | Use bearer auth and keep CORS restricted outside local development | 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). ## Safety Model ProxmoxMCP-Plus is an access layer, not a replacement for Proxmox RBAC, network controls, or client-side MCP approval prompts. The project gives operators several control points: - Proxmox API tokens decide what the backend can do. - `PROXMOX_API_KEY` protects the OpenAPI bridge by default. - `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. - TLS verification is enforced unless development mode is explicitly enabled. - `command_policy` controls command execution and high-risk operations. - `approval_token` can gate command execution and high-risk mutating actions. - MCP Streamable HTTP deployments can use DNS rebinding protection plus Host and Origin allowlists. - Optional MCP tool allowlists or denylists reduce the runtime tool surface; they do not replace Proxmox RBAC. - Logs are designed to avoid exposing command and credential material. Read the [Security Guide](docs/wiki/Security%20Guide.md) before exposing the server outside a trusted local environment. ## Core Platform Capabilities 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. Supported workflow areas: | Capability Area | Availability | | --- | --- | | VM create / start / stop / delete | Available | | VM snapshot create / rollback / delete | Available | | Backup create / restore | Available | | ISO download / delete | Available | | LXC create / start / stop / delete | Available | | Container SSH-backed command execution | Available | | Container authorized_keys update | Available | | Persistent job store for long tasks | Available | | MCP job control tools (`list_jobs`, `get_job`, `poll_job`, `cancel_job`, `retry_job`) | Available | | OpenAPI `/jobs` endpoints with explicit status codes | Available | | Local OpenAPI `/livez`, `/readyz`, `/health`, and schema | Available | | Docker native MCP Streamable HTTP at `/mcp` | Available | | Docker image build and `/livez` | Available | Validation and contract entry points in this repository: - `pytest -q --cov=proxmox_mcp --cov-report=term-missing --cov-fail-under=75` - `ruff check .` - `mypy src --ignore-missing-imports` - `pip-audit -r requirements.txt` - `tests/integration/test_real_contract.py` - `tests/scripts/run_real_e2e.py` `tests/scripts/run_real_e2e.py` now prefers `proxmox-config/config.live.json` or `PROXMOX_MCP_E2E_CONFIG`. This avoids accidentally running live checks against a machine-specific default `config.json`. ## Long-Running Jobs 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`. Long-running tools such as VM create/start/stop, container create/start/stop, snapshot changes, backup/restore, and ISO download/delete now return both: - `task_id`: the raw Proxmox `UPID` - `job_id`: the stable server-side job record The job record stores: - current status and progress - retry count and prior `UPID`s - latest result payload or failure reason - audit history for create, poll, retry, and cancel actions By default the job store persists to `proxmox-jobs.sqlite3`, so restart does not lose in-flight or completed job metadata. Audit events are appended to a separate SQLite table. Existing history is migrated on startup and the API's `audit_log` format stays unchanged. Retention is unlimited by default; set `jobs.audit_retention_days` to a positive number in JSON config to prune expired events at startup and when each job is updated. This never deletes the job itself. Stop all workers sharing the database and back it up before this upgrade. Do not run old and new versions against the same database; restore the pre-upgrade backup if downgrading and retaining audit history is required. A cancellation request is not completion. Poll until the task is failed/cancelled before calling `retry_job`; pending cancellation cannot be retried. ### MCP Job Tools - `list_jobs` - `get_job` - `poll_job` - `cancel_job` - `retry_job` ### OpenAPI Job Routes When the OpenAPI proxy is enabled and a local `JobStore` is available, these routes are exposed directly: | Path | Method | Purpose | Success Codes | | --- | --- | --- | --- | | `/jobs` | `GET` | list persisted jobs | `200` | | `/jobs/{job_id}` | `GET` | fetch one job, optional `refresh=true` | `200` | | `/jobs/{job_id}/poll` | `POST` | refresh status from Proxmox | `200` | | `/jobs/{job_id}/cancel` | `POST` | request cancellation | `202` | | `/jobs/{job_id}/retry` | `POST` | replay a stored retry recipe | `202` | Common error codes: - `404`: unknown `job_id` - `409`: the job exists but that operation is not valid now - `503`: the OpenAPI proxy was started without a local `JobStore` `tests/scripts/run_real_e2e.py` now prefers `proxmox-config/config.live.json` or `PROXMOX_MCP_E2E_CONFIG`. This avoids accidentally running live checks against a machine-specific default `config.json`. ## Positioning Against Common Approaches | Capability | Official Proxmox API | One-off scripts | ProxmoxMCP-Plus | | --- | --- | --- | --- | | MCP for LLM and AI agent workflows | No | No | Yes | | OpenAPI surface for standard HTTP tooling | No | Usually no | Yes | | VM and LXC operations in one interface | Low-level only | Depends | Yes | | Snapshot, backup, and restore workflows | Low-level only | Depends | Yes | | Persistent async job tracking and retry | No | Rare | Yes | | Container command execution with policy controls | No | Custom only | Yes | | Docker distribution path | No | Rare | Yes | | Repository-level live-environment verification | N/A | Rare | Yes | ## Scenario Templates Ready-to-copy examples live in [`docs/examples/`](docs/examples/README.md): - [Create a test VM](docs/examples/create-test-vm.md) - [Roll back a risky change with snapshots](docs/examples/rollback-snapshot.md) - [Download an ISO and create an LXC](docs/examples/download-iso-and-create-lxc.md) These are written for both human operators and LLM-driven usage. ## Documentation 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. | If you need to... | Start here | | --- | --- | | Understand the project and deployment flow | [Wiki Home](docs/wiki/Home.md) | | Configure and run against a Proxmox environment | [Operator Guide](docs/wiki/Operator%20Guide.md) | | Connect Claude Desktop, Cursor, VS Code, Codex, Open WebUI, or HTTP clients | [Client Setup Guide](docs/wiki/Client%20Setup.md) | | Choose the right tool for a workflow | [Tool Selection Guide](docs/wiki/Tool%20Selection%20Guide.md) | | Review docs quality goals, media plan, and publishing checklist | [Documentation Quality Plan](docs/wiki/Documentation%20Quality%20Plan.md) | | Review integration patterns and transport details | [Integrations Guide](docs/wiki/Integrations%20Guide.md) | | Install from MCP-aware IDEs and agents | [Agent Installation](docs/agent-installation.md) | | Enable LXC command execution over SSH | [Container Command Execution](docs/container-command-execution.md) | | Review security and command policy | [Security Guide](docs/wiki/Security%20Guide.md) | | Inspect tool parameters, prerequisites, and behavior | [API & Tool Reference](docs/wiki/API%20%26%20Tool%20Reference.md) | | Debug startup, auth, or health issues | [Troubleshooting](docs/wiki/Troubleshooting.md) | | Work on the codebase or release it | [Developer Guide](docs/wiki/Developer%20Guide.md) | | Review release and upgrade notes | [Release & Upgrade Notes](docs/wiki/Release%20%26%20Upgrade%20Notes.md) | Published wiki: - [GitHub Wiki Home](https://github.com/RekklesNA/ProxmoxMCP-Plus/wiki/Home) ## Repo Layout - `src/proxmox_mcp/`: MCP server, config loading, security, OpenAPI bridge - `main.py`: MCP entrypoint for local and client-driven usage - `docker-compose.yml`: HTTP/OpenAPI runtime - `requirements/`: auxiliary dependency sources and runtime install lists - `scripts/`: helper startup scripts for local workflows - `tests/scripts/run_real_e2e.py`: live Proxmox and Docker/OpenAPI path - `tests/`: unit and integration coverage - `docs/examples/`: scenario-driven prompts and HTTP examples - `docs/wiki/`: longer-form operator, integration, and reference docs ## Development Checks ```bash pytest -q --cov=proxmox_mcp --cov-report=term-missing --cov-fail-under=75 ruff check . mypy src --ignore-missing-imports pip-audit -r requirements.txt python -m build ``` Paramiko 5.0.0 or newer is required so `pip-audit` can run without a `CVE-2026-44405` exception. ## License [MIT](LICENSE) ### ISO installation and LXC network configuration Use `list_isos` to find an existing ISO volume (or `download_iso` to obtain one). `create_vm` accepts `iso_volume="local:iso/debian.iso"`, mounts it on `ide3` by default and boots CD-ROM before disk. `update_vm_config` can mount or change that ISO, eject with `iso_volume="none"`, set `boot_order="scsi0;ide3"`, or change `network_bridge` on `net0` while retaining MAC/VLAN/firewall settings. Choose a free `cdrom_device`; existing data disks and cloud-init drives are never replaced. Media and bridge edits read current configuration and therefore need `VM.Audit` as well as the relevant configuration privileges. Existing sizing/cloud-init-only updates still do not require a preliminary read. LXC uses OS templates, not installer ISOs. `create_container` retains DHCP by default and now accepts `network_bridge`, `ip="192.168.1.50/24"`, `gw="192.168.1.1"`, `ip6` and `gw6`. `update_container_network` edits those fields on an existing interface (default `net0`, selectable through `net31`) and preserves all unspecified options. Use an empty gateway string to remove it; changing to DHCP/manual removes the old gateway for that address family. Network changes can interrupt guest connectivity. Both edit tools follow named-target, read-only and high-risk approval policies. Add `update_container_network` to custom high-risk lists and desired tool allowlists. See [v0.5.19 release notes](docs/releases/v0.5.19.md) for upgrade details.