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_ids, 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:

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.

Native MCP HTTP with Docker

Use this path when a remote MCP client supports Streamable HTTP:

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:

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.

When serving MCP HTTP behind a reverse proxy, keep DNS rebinding protection enabled and allow only the hostnames you expect:

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_DNS_REBINDING_PROTECTION=true \
  -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

OpenAPI bridge with Docker

OpenAPI mode is the default Docker runtime and requires an API key:

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:

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

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.

Recommended stdio config:

{
  "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:

{
  "mcpServers": {
    "proxmox-mcp-plus": {
      "command": "uvx",
      "args": ["proxmox-mcp-plus"],
      "env": {
        "PROXMOX_MCP_CONFIG": "/path/to/ProxmoxMCP-Plus/proxmox-config/config.json"