ProxmoxMCP-Plus

The project provides a bridge to manage Proxmox VE environments through several core functional areas:

• Lifecycle Management: Operations for VMs and LXC containers.
• Data Protection: Snapshots, rollbacks, backups, and restores.
• Provisioning: ISO and template workflows.
• Inspection: Monitoring of clusters, nodes, and storage.
• Container Interaction: SSH-backed command execution within LXC containers.
• Job Management: Persistent tracking of long-running jobs including retry, cancel, polling, and audit history.
• Integration: OpenAPI bridging for the MCP tool surface.
• Target Isolation: Support for named Proxmox targets with isolated connections and safety policies.
• Schema Control: Opt-in MCP tool allowlists and denylists to limit the tools exposed to clients.

The project is organized as follows:

Command execution tools (like execute_*) are governed by a command_policy. You can define how commands are validated to prevent unauthorized or destructive actions.

Supported Modes:

• deny_all: Blocks all commands unless they match specified allow_patterns.
• allowlist: Requires commands to match allow_patterns.
• audit_only: Allows commands to run but evaluates them against the rules for logging/auditing.

Additional Controls:

• deny_patterns: A list of patterns that will block known-dangerous commands (e.g., rm -rf is blocked by default).
• require_approval_token: Forces the caller to provide a specific token to execute the command.
• approval_token: The specific token value that the server validates against.

ProxmoxMCP-Plus acts as an operator-facing control layer on top of Proxmox RBAC. It does not replace Proxmox's native security but adds several layers of protection:

• Authority: Proxmox API token permissions remain the ultimate source of authority.
• Authentication:
  • OpenAPI mode requires PROXMOX_API_KEY by default.
  • Native MCP HTTP mode can require a separate MCP_API_KEY Bearer token.
• Encryption: TLS validation is enforced by default. To disable this for development, set security.dev_mode=true.
• Execution Control: Use command_policy and approval_token to gate high-risk operations or specific commands.
• Network Security: MCP HTTP deployments support DNS rebinding protection and allowlisting for Host and Origin headers.
• Auditability: Logs are designed to prevent the leakage of credentials or sensitive command material.

Mutating tools that trigger asynchronous Proxmox tasks return both a raw Proxmox task_id and a stable job_id.

• job_id: The stable identifier used by both MCP and OpenAPI for tracking long-running operations. These records persist in the configured SQLite database and survive process restarts.
• task_id: The raw Proxmox UPID. This value can change if a job is retried.

OpenAPI Job Status Codes

• 200: list, fetch, or poll succeeded
• 202: cancel or retry request accepted
• 404: unknown job_id
• 409: the job exists but cannot perform that action now
• 503: the OpenAPI wrapper has no local JobStore

Job Operations

• retry_job: Only works if the job was created with a stored retry recipe.
• cancel_job: Best-effort; follows Proxmox task cancellation semantics.

Many Proxmox mutations (VM/LXC creation, snapshots, backups, ISO management) are asynchronous. ProxmoxMCP-Plus wraps these in a persistent job layer using a JobStore (defaulting to proxmox-jobs.sqlite3).

Job Identifiers

When a long-running tool is called, it returns two IDs:

1. task_id: The raw Proxmox UPID.
2. job_id: A stable server-side job record used for tracking via the MCP or OpenAPI layers.

The job record includes status, progress, retry counts, prior UPIDs, results/failures, and audit history.

Managing Jobs via MCP

Use these tools to interact with the job layer:

• list_jobs
• get_job
• poll_job
• cancel_job
• retry_job

ProxmoxMCP-Plus acts as an access layer and relies on several layers of security. It is not a replacement for Proxmox RBAC.

Security Control Points

• Proxmox RBAC: Proxmox API tokens determine the actual permissions of the backend.
• OpenAPI Protection: The PROXMOX_API_KEY protects the OpenAPI bridge by default.
• MCP Endpoint Protection: The native Streamable HTTP /mcp endpoint can be protected with Bearer authentication using MCP_API_KEY.
• Command Control: Use command_policy to control execution and high-risk operations, and approval_token to gate mutating actions.
• Network Security: TLS verification is enforced by default. MCP Streamable HTTP deployments support DNS rebinding protection and Host/Origin allowlists.
• Tool Surface: You can use optional MCP tool allowlists or denylists to restrict the available tool surface.

OpenCode does not require manual sourcing of environment variables. The opencode.jsonc configuration uses a shell command that automatically sources the proxmox-mcp.env file before executing the MCP command via uvx.

Ensure your opencode.jsonc command follows this pattern:

"command": ["sh", "-c", ". ./proxmox-mcp.env && uvx --from git+https://github.com/RekklesNA/ProxmoxMCP-Plus.git proxmox-mcp"]

ProxmoxMCP-Plus supports three distinct transport modes. The core tool set remains identical across all modes; only the communication method changes:

1. MCP stdio mode: The default mode where assistants (like Claude Desktop) launch the server as a subprocess and communicate via standard input/output.
2. MCP Streamable HTTP mode: The server exposes a native MCP endpoint at /mcp. This is intended for MCP clients that support Streamable HTTP.
3. OpenAPI mode: A FastAPI wrapper that exposes the MCP server's tools as standard HTTP endpoints. This is useful for non-MCP clients or integration into existing web services.

Authentication requirements vary depending on the access method and configuration:

• Proxmox API Access: Requires valid proxmox and auth sections or a named targets configuration.
• Native MCP Streamable HTTP: Optionally requires Authorization: Bearer <MCP_API_KEY> if MCP_API_KEY is set.
• OpenAPI Access: Requires Authorization: Bearer <PROXMOX_API_KEY> by default. For local development without an API key, set the environment variable PROXMOX_ALLOW_NO_AUTH=true.
• SSH-backed Tools: Require a valid ssh configuration.
• Command Execution: Subject to command-policy checks. Depending on the policy, requests may be allowed, denied, or require an approval_token.

Most mutating operations return two identifiers:

• task_id: The raw Proxmox UPID.
• job_id: The persistent ProxmoxMCP-Plus job record.

Use the following tools to manage these operations:

Tip: To preserve job history across server restarts, ensure jobs.sqlite_path is configured on durable storage.