ProxmoxMCP-Plus v0.5.14

ProxmoxMCP-Plus v0.5.14

Release date: 2026-08-11

Optional Bearer authentication for native MCP HTTP

Native Streamable HTTP deployments can now set MCP_API_KEY to protect the /mcp
endpoint with application-level Bearer authentication. Requests that omit the header,
use another authentication scheme, or provide the wrong token receive 401 Unauthorized
with WWW-Authenticate: Bearer.

The new token is deliberately independent of PROXMOX_API_KEY, which continues to
protect only the OpenAPI bridge on port 8811. This allows operators to expose and rotate
the two surfaces independently.

Authentication uses constant-time token comparison. The middleware is implemented as a
direct ASGI pass-through: successful Streamable HTTP and text/event-stream responses
are not collected or buffered.

Compatibility

• MCP_API_KEY is optional and affects only native Streamable HTTP mode.
• STDIO and SSE transports are unchanged.
• Existing unauthenticated Streamable HTTP deployments continue to start, but now emit a
  security warning explaining that reachable clients can invoke MCP tools.
• Existing PROXMOX_API_KEY and PROXMOX_ALLOW_NO_AUTH behavior for OpenAPI is unchanged.

Upgrade

Generate a separate secret before starting a remotely reachable native MCP HTTP service:

export MCP_API_KEY="$(openssl rand -hex 32)"
docker compose --profile mcp-http up -d proxmox-mcp-http

Configure the MCP client to send:

Authorization: Bearer <MCP_API_KEY>

Continue to use TLS termination, network ingress restrictions, DNS rebinding protection,
and explicit Host/Origin allowlists. These controls address different threats and do not
replace caller authentication.

Validation

The release gate covers missing, malformed, incorrect, and matching credentials;
constant-time comparison; unchanged lifespan handling; unbuffered multi-chunk SSE event
forwarding; the unauthenticated compatibility path; Python 3.11 and 3.12 CI; Ruff; Mypy;
CodeQL; dependency auditing; package metadata; and multi-architecture container checks.

Rollback

Pin PyPI or source installs to 0.5.13, or use the GHCR tag 0.5.13. Rolling back removes
native /mcp Bearer enforcement, so retain a reverse proxy or network-level authentication
control until the deployment is upgraded again.

ProxmoxMCP-Plus v0.5.13

ProxmoxMCP-Plus v0.5.13

Release date: 2026-08-10

Read-only log inspection

This release adds five read-only MCP tools for investigating Proxmox nodes, tasks, cluster events, and firewall activity without leaving the MCP client:

• get_node_syslog
• get_task_log
• get_cluster_log
• get_node_firewall_log
• get_guest_firewall_log for QEMU VMs and LXC containers

All five tools use Proxmox GET endpoints and do not change cluster state. Access remains subject to Proxmox permissions. Depending on the requested log and its owner, the configured user or API token may need Sys.Syslog, Sys.Audit, or VM.Console on the relevant cluster, node, or guest path. Firewall logging must also be enabled for traffic entries to appear.

Logs can contain usernames, task identifiers, IP addresses, service names, and other sensitive operational details. Grant only the permissions needed and avoid sharing returned logs without review.

Thanks to DevLeti for contributing the inspection tools in PR #116.

Reliable STDIO shutdown

STDIO servers now exit cleanly when they receive SIGINT or SIGTERM, avoiding the CPython _enter_buffered_busy abort that could occur while an MCP SDK reader thread still owned the shared standard-input buffer. Application resources are closed before the process exits, and the shutdown path deliberately avoids high-level standard-stream flushing that could deadlock behind an SDK writer.

SSE and Streamable HTTP retain their existing graceful SystemExit behavior. Thanks to scottrus for diagnosing and contributing the original fix in PR #113.

Compatibility

• No configuration migration is required.
• Existing tools, schemas, ports, and transport configuration remain compatible.
• The new inspection tools are additive and read-only.
• MCP clients that cache tool definitions may need to reconnect or refresh their tool list after upgrading.

Validation

The release quality gate covers Python 3.11 and 3.12 tests with coverage enforcement, Ruff, Mypy, CodeQL, dependency auditing, package builds, Twine metadata validation, runtime-to-manifest parity, and multi-architecture container publication checks.

Upgrade and rollback

• Upgrade normally from PyPI, GHCR, or source, then reconnect the MCP client if the new tools are not immediately visible.
• No application, Docker, or Proxmox configuration change is required solely for this release.
• To roll back, pin PyPI or source installs to 0.5.12, or use the GHCR tag 0.5.12.

ProxmoxMCP-Plus v0.5.12

ProxmoxMCP-Plus v0.5.12

Release date: 2026-07-29

Immutable Docker Release Actions

This release completes the supply-chain hardening of the GHCR publication workflow by pinning every third-party Docker Action to a reviewed full commit SHA:

• docker/login-action v4.6.0
• docker/metadata-action v6.2.0
• docker/build-push-action v7.3.0
• docker/setup-qemu-action v4.2.0
• docker/setup-buildx-action v4.2.0

The login-action pin was refreshed from v4.4.0 during review to include the v4.5 and v4.6 dependency updates and scoped-config path hardening. All five pinned commits were resolved against their official Docker Action repositories before release.

Thanks to mirkosalvato1-ctrl for opening PR #108 and proposing the original pinning change.

Regression Protection

The release metadata tests now enumerate every docker/* Action reference in the GHCR workflow and require each reference to be a lowercase 40-character commit SHA. Adding a mutable major tag such as @v4 will fail CI.

The Python base image and QEMU helper image remain pinned by OCI digest.

Compatibility

• MCP tools, schemas, ports, transports, and runtime configuration are unchanged.
• The native linux/amd64 and linux/arm64 images introduced in v0.5.11 remain available under the same GHCR tags.
• The native ARM64 post-publication pull and /livez health check remains a required GHCR release gate.
• No migration is required.

Validation

The release quality gate covers Python 3.11 and 3.12 tests with coverage enforcement, Ruff, Mypy, CodeQL, dependency auditing, package builds, Twine metadata validation, runtime-to-manifest parity, actionlint, immutable Action reference checks, multi-architecture publication, and native ARM64 post-publication runtime validation.

Upgrade Notes

• Upgrade normally from PyPI, GHCR, or source.
• No application or Docker configuration changes are required.

ProxmoxMCP-Plus v0.5.11 — Native ARM64 containers

ProxmoxMCP-Plus v0.5.11

Release date: 2026-07-29

Native ARM64 Container Image

This release publishes the GHCR container for both linux/amd64 and linux/arm64 under the same image tags.

Docker now selects the native image automatically on Apple Silicon and other ARM64 hosts. These systems no longer need to run the AMD64 image through QEMU emulation when pulling the published image.

Release Pipeline Safety

The release workflow uses Docker Buildx to publish one multi-architecture manifest. QEMU registration is limited to ARM64, the only additional target. The newly introduced QEMU and Buildx actions are pinned to reviewed full commit SHAs, and the QEMU helper image is pinned by OCI digest.

The Docker build context now excludes local agent/tool state, environment files, private-key file patterns, and non-example Proxmox JSON configuration files. This prevents local development credentials or runtime configuration from being copied into image layers by COPY . ..

Python packaging tools (pip, setuptools, and wheel) are removed after the application is installed because they are not required at runtime. This reduces the final image attack surface and prevents vulnerabilities in dormant build-only code from shipping with the service.

The multi-architecture Python base image is pinned by OCI digest. Regression tests verify that both architectures remain configured, the new third-party actions remain immutable, the sensitive build-context exclusions remain present, the base image remains immutable, and the runtime packaging toolchain remains removed.

After publication, a native GitHub-hosted ARM64 runner pulls the published image, verifies that the tag contains both Linux architectures, starts the ARM64 container, checks /livez, confirms uname -m reports aarch64, and confirms the process is not running as root. The GHCR workflow does not pass unless this post-publication check succeeds.

Container Vulnerability Review

Docker Scout analysis removed two high-severity findings by removing the dormant Python packaging toolchain. The remaining findings are in Debian Trixie's essential perl-base package:

• CVE-2026-12087
• CVE-2026-48959
• CVE-2026-48962

Debian classifies these as minor no-dsa issues for Trixie, and the current Trixie repository does not provide a fixed package. Their vulnerable paths require an application to invoke Perl Socket or Perl archive-processing APIs with attacker-controlled inputs. ProxmoxMCP-Plus does not invoke Perl or expose those APIs. Removing the essential package would make the base system unsafe, so the residual base-image advisories are documented rather than hidden or bypassed.

Compatibility

• Existing AMD64 deployments continue to receive a native AMD64 image.
• ARM64 hosts receive a native ARM64 image from the same tag.
• Image names, ports, environment variables, transports, and MCP tools are unchanged.
• No runtime configuration migration is required.

Validation

The release quality gate covers Python 3.11 and 3.12 tests with coverage enforcement, Ruff, Mypy, CodeQL, dependency auditing, package builds, Twine metadata validation, runtime-to-manifest parity, multi-architecture workflow regression checks, and Docker build-context safety checks.

The published 0.5.11 and latest tags must expose both linux/amd64 and linux/arm64. The ARM64 image is pulled explicitly on a native ARM64 runner and its application health endpoint is checked before issue #109 is closed.

Upgrade Notes

• Pull ghcr.io/rekklesna/proxmoxmcp-plus:0.5.11 or latest normally.
• Docker automatically selects the correct architecture.
• No Compose or MCP client changes are required.

ProxmoxMCP-Plus v0.5.10 - VM and container Notes tools

ProxmoxMCP-Plus v0.5.10

Release date: 2026-07-23

VM and Container Notes

This release adds two MCP tools for managing the Proxmox Notes field:

• set_vm_description updates the description of one QEMU virtual machine.
• set_container_description updates the description of one LXC container.

Both tools accept node, vmid, and description, then use the native Proxmox configuration endpoint. The supplied text replaces the existing Notes value; pass an empty string to clear it.

The new tools complement get_vm_config and get_container_config, which already expose the stored description. They deliberately target one guest at a time and do not add selector or bulk-update behavior.

Permissions and Safety

The configured Proxmox API token must be allowed to update the target guest configuration. Proxmox remains the authorization boundary; this release does not broaden token permissions.

Descriptions are passed as data to the Proxmox API. They are not executed as commands, written to local files, or included in command logs.

Compatibility

• Existing MCP tool names and inputs are unchanged.
• No runtime configuration migration is required.
• Clients that cache the tool manifest should refresh it to discover the two new tools.

Validation

The release quality gate covers Python 3.11 and 3.12 tests with coverage enforcement, Ruff, Mypy, CodeQL, dependency auditing, package builds, Twine metadata validation, and runtime-to-manifest parity.

Upgrade Notes

• Upgrade normally from PyPI, Docker/GHCR, or source.
• Refresh the MCP client tool list after upgrading.
• Test description updates on a non-production guest before adopting the tools in automated workflows.

ProxmoxMCP-Plus v0.5.9 — Resource pool-scoped guest creation

ProxmoxMCP-Plus v0.5.9

Release date: 2026-07-16

Resource-Pool-Scoped VM and LXC Creation (Issue #104)

This release adds an optional pool argument to the existing create_vm and create_container MCP tools. The value is passed directly to the native Proxmox QEMU or LXC creation endpoint so operators can create new guests inside a dedicated Proxmox resource pool.

This enables a privilege-separated API token to use a resource pool as the security boundary for AI-driven provisioning. For example, an operator can grant VM allocation and configuration privileges on /pool/claude-lab without granting global allocation privileges across production guests.

pool means a Proxmox resource pool. It is separate from the storage argument used for VM disks and LXC root filesystems.

Backward Compatibility

• pool is optional on both tools.
• When pool is omitted or empty, the Proxmox request payload is unchanged from v0.5.8.
• Existing positional and keyword callers remain compatible because the new argument is appended to each public Python method signature.
• No runtime configuration migration is required.

Permissions

The configured Proxmox API token must have the VM permissions required for creation and Pool.Allocate on the target resource pool. Permission assignment remains an operator responsibility; ProxmoxMCP-Plus does not broaden token privileges or fall back to global allocation.

Test Client Dependency

Development and test installs now include httpx2>=2.0.0,<3.0.0, which is the supported client backend for current Starlette TestClient. This removes the deprecated fallback to the legacy httpx backend without changing runtime dependencies.

The development test stack also moves to pytest>=9.0.3,<10.0.0 and pytest-asyncio>=1.4.0,<2.0.0. This excludes pytest versions affected by PYSEC-2026-1845 instead of suppressing the dependency-audit result.

Validation

• Added MCP-level regression tests proving pool reaches both native Proxmox create requests.
• Added compatibility assertions proving omitted pool values do not alter existing request payloads.
• Treating StarletteDeprecationWarning as an error passes for the complete OpenAPI proxy test module.
• The full release quality gate covers tests with coverage enforcement, Ruff, Mypy, dependency audit, package build, metadata validation, and distribution checks.

Upgrade Notes

• Upgrade normally from PyPI, Docker/GHCR, or source.
• Existing calls require no changes.
• To opt in, pass pool="claude-lab" (or another Proxmox resource-pool name) to create_vm or create_container.

ProxmoxMCP-Plus v0.5.8 — Windows SSH compatibility fix

ProxmoxMCP-Plus v0.5.8

Release date: 2026-06-07

Windows SSH Compatibility Fixes (Issue #100)

This release fixes four critical bugs that prevented execute_container_command and get_node_status from working correctly on Windows 11 with Claude Code (VS Code extension). All bugs are also observable on any platform that runs the MCP server headless without a TTY.

Bug 1 - SSH command never includes the username

• File: src/proxmox_mcp/tools/console/container_manager.py
• Method: _execute_via_system_ssh()
• Impact: execute_container_command never worked on Windows out of the box.

_execute_via_system_ssh() correctly read key_file and port from the SSH config, but never added the user field. On Linux, SSH often defaults to the current system user which may match. On Windows, SSH falls back to the Windows login name (e.g. manta), which has no access to the Proxmox host. The command silently timed out after 70 seconds on every call.

Fix: Explicitly pass -l <user> to the OpenSSH command so behaviour is consistent across platforms.

Bug 2 - SSH subprocess hangs because stdin is not closed (Windows-specific)

• File: src/proxmox_mcp/tools/console/container_manager.py
• Method: _execute_via_system_ssh()
• Impact: 70-second hang on every execute_container_command call on Windows.

subprocess.run with capture_output=True only redirects stdout and stderr. stdin was inherited from the parent process, which in the case of an MCP server is a pipe connected to Claude Code. On Windows, OpenSSH read from this inherited stdin and blocked indefinitely, even when -o BatchMode=yes was set. This did not reproduce on Linux.

Fix: Pass stdin=subprocess.DEVNULL to close stdin at the OS level before SSH starts.

Bug 3 - SSH hangs waiting for interactive prompts when running headless

• File: src/proxmox_mcp/tools/console/container_manager.py
• Method: _execute_via_system_ssh()
• Impact: Hangs on first connection or unknown hosts when running headless.

_execute_via_system_ssh() did not pass -o BatchMode=yes to SSH. When the MCP server runs headless (no TTY attached), SSH waited indefinitely for interactive input such as host key confirmation prompts or password prompts.

Fix: Pass BatchMode=yes and StrictHostKeyChecking=accept-new so SSH fails fast on prompts and silently trusts first-seen host keys.

Bug 4 - get_node_status always shows Status: UNKNOWN and CPU Cores: N/A

• Files:
  • src/proxmox_mcp/tools/node.py
  • src/proxmox_mcp/formatting/templates.py
• Impact: Status and CPU fields were always wrong regardless of node health.

Problem A: templates.py node_status() reads status.get('status', 'unknown'). The Proxmox API endpoint GET /nodes/{node}/status does not include a status field in its response. That field only exists in the node list endpoint GET /nodes. Status always fell back to 'unknown'.

Fix A: Inject "status": "online" into the result in get_node_status when missing. A successful API response is itself proof the node is reachable.

Problem B: The template read status.get('maxcpu', 'N/A') for the CPU core count. The node status API does not return a top-level maxcpu field. The CPU count is nested under cpuinfo.cpus.

Fix B: Update the template to read the correct nested field, with maxcpu as a forward-compatibility fallback.

Tests

• Added 5 regression tests in tests/test_container_console.py covering all three SSH fixes (-l user, stdin=DEVNULL, BatchMode/accept-new).
• Added 3 regression tests in tests/test_server.py covering the missing status injection, the cpuinfo.cpus CPU cores path, and the maxcpu fallback.
• Full test suite: 185 passed, 1 skipped (pre-existing).

Runtime Impact

• No public API, MCP tool surface, or configuration schema changed.
• No migration is required from v0.5.7.
• All changes are pure bug fixes for Windows / headless environments; behaviour on Linux/POSIX is unchanged for users who already had a working configuration.

Upgrade Notes

• Upgrade normally from PyPI, Docker/GHCR, or source.
• Windows users running the MCP server through Claude Code, Cursor, or any other headless client should immediately see execute_container_command and get_node_status work as expected.

ProxmoxMCP-Plus v0.5.7

ProxmoxMCP-Plus v0.5.7

Release date: 2026-05-30

Visual Documentation Improvements

• Replaced the README hero architecture diagram with a new publication-style SVG.
• The new diagram is grounded in the actual project architecture:
  • MCP stdio clients
  • MCP Streamable HTTP at /mcp
  • OpenAPI automation through /docs, /openapi.json, /health, /readyz, and /metrics
  • FastMCP server boundary
  • OpenAPI proxy
  • built-in tool registry and domain tool plugins
  • command policy, config loading, observability, and persistent jobs
  • Proxmox VE REST API, QEMU Guest Agent, SSH-backed pct exec, and SQLite-backed job state

Runtime Impact

• No runtime tools, endpoints, package dependencies, or configuration requirements changed in this release.
• No migration is required from v0.5.6.

Upgrade Notes

• Upgrade normally from PyPI, Docker/GHCR, or source.
• If a downstream documentation renderer cannot display the new SVG, continue using v0.5.6 or pin the previous README asset in that renderer.

ProxmoxMCP-Plus v0.5.6

ProxmoxMCP-Plus v0.5.6

Release date: 2026-05-30

Documentation Experience Improvements

• Reworked the README first-screen positioning, quick-start flow, and documentation routing so new users can choose between MCP stdio, MCP Streamable HTTP, and OpenAPI without reading the full wiki first.
• Added one-click install links for supported VS Code and Cursor MCP flows, plus safer copy-ready stdio configuration examples.
• Added a compact README tool-selection table that maps common Proxmox operator goals to the appropriate MCP and OpenAPI workflows.
• Added a README safety model summary that routes users to the full security guide before exposing the server outside a trusted local environment.

Wiki Improvements

• Rebuilt the wiki home page around task-oriented routing and a five-minute installation path.
• Added Client Setup for Claude Desktop, Cursor, VS Code, Codex, OpenCode, Open WebUI, generic stdio clients, Streamable HTTP clients, and HTTP/OpenAPI consumers.
• Added Tool Selection Guide for VM, LXC, snapshot, backup, ISO, command execution, job tracking, and OpenAPI workflows.
• Added Documentation Quality Plan to track README standards, wiki standards, media plans, docs-site plans, LLM documentation entry points, and release documentation checks.
• Updated the wiki sidebar and wiki seed README to include the new pages.

LLM Documentation Entry Point

• Added docs/llms.txt as a compact documentation index for AI clients and coding agents.

Runtime Impact

• No runtime code paths, tools, endpoints, or configuration requirements changed in this release.
• No migration is required from v0.5.5.

Upgrade Notes

• Upgrade normally from PyPI, Docker/GHCR, or source.
• Review the new Client Setup and Tool Selection Guide pages when onboarding new users or new MCP clients.

ProxmoxMCP-Plus v0.5.5

ProxmoxMCP-Plus v0.5.5

Release date: 2026-05-29

Quality Improvements

• Server shutdown now explicitly closes the Proxmox API SSH tunnel manager, so API tunnel processes are released during graceful stop and test teardown instead of relying only on atexit.
• CI now validates the project on both Python 3.11 and Python 3.12, matching the supported Python versions declared in package metadata.
• The CI coverage gate is raised from 70% to 75%.

Tests

• Added SSH tunnel lifecycle coverage for disabled tunnels, reachable endpoints, startup waits, early SSH exits, timeouts, graceful termination, and forced kill cleanup.
• Added formatting coverage for components, colors, formatters, and theme fallback helpers.
• Added backup user-path coverage for listing, creating, restoring, and deleting backups.

Upgrade Notes

• No mandatory config migration is required.
• API tunnel users should see the same runtime behavior, with cleaner process cleanup during shutdown.