Noureddine RAMDI / ProxmoxMCP-Plus: A Python toolset for advanced Proxmox MCP protocol interaction

Created Sat, 23 May 2026 20:41:14 +0000 Modified Sat, 23 May 2026 20:41:27 +0000
930 Words
github-stars python proxmox mcp automation docker sysadmin

RekklesNA/ProxmoxMCP-Plus

ProxmoxMCP-Plus tackles a specific challenge in managing Proxmox VE environments: interacting with the MCP protocol beyond the usual REST API. For those who manage Proxmox clusters or labs, having flexible programmatic control is essential, and this project provides a Python-based toolkit designed for that.

What ProxmoxMCP-Plus is and how it works

At its core, ProxmoxMCP-Plus is a Python package and runtime environment that facilitates communication with the Proxmox MCP protocol, which is an alternative, lower-level API compared to the more common REST interface. The MCP protocol supports streaming and is designed to handle stateful operations and event-driven interactions with Proxmox nodes.

The project organizes its setup through JSON configuration files, where users specify connection details such as the Proxmox host, port, authentication tokens, and optional SSH settings for command execution inside containers. This configuration-driven approach aligns well with sysadmin workflows, allowing environment-specific adjustments without code changes.

The architecture supports persisting job states either locally using SQLite or through alternative storage options configured in the JSON files. This persistence is crucial for long-running or asynchronous tasks that interact with Proxmox resources.

Additionally, ProxmoxMCP-Plus offers multiple runtime options to suit different deployment scenarios. You can run it directly from PyPI using a Python environment, or use Docker containers that are prebuilt and published on GitHub Container Registry. The Docker mode also supports different communication modes, including a Streamable HTTP mode for MCP clients.

Code quality, design choices, and tradeoffs

The project is implemented in Python, which provides good accessibility and ease of extension for sysadmins and developers familiar with the language. The codebase is modular, with clear separation between configuration management, MCP protocol handling, and job persistence.

One clear design tradeoff is relying on JSON files for configuration rather than more dynamic or encrypted configuration stores. While this keeps the setup simple and transparent, it requires careful manual management of sensitive data like tokens.

The support for job state persistence using SQLite by default is pragmatic, offering a lightweight embedded database that avoids external dependencies. However, this may not scale well for very large environments or distributed setups, where external databases would be preferable.

The Docker-based deployment is well thought out, exposing environment variables for key configuration points and enabling users to switch easily between the OpenAPI default mode and the native MCP Streamable HTTP mode. This flexibility is a plus for integrating with different Proxmox client tools.

Under the hood, the Python code leverages standard libraries and conventions, which helps with maintainability and lowers the barrier for contributions or customizations. The project does not appear to over-engineer or introduce unnecessary complexity, sticking to its niche purpose.

Quick start

1. Prepare Proxmox access

Start by reviewing the official Proxmox documentation if you are setting up a new environment:

  • Proxmox VE installation guide
  • Proxmox VE API guide
  • Proxmox VE administration guide
  • Linux Container guide

Create a configuration file from the example:

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

Edit proxmox-config/config.json to set your environment details. Minimum required fields include:

  • proxmox.host
  • proxmox.port
  • auth.user
  • auth.token_name
  • auth.token_value

Optionally add an ssh section for container command execution, and a jobs section if you want job state persisted outside the default SQLite file.

For live verification, use a separate live config file copied from proxmox-config/config.live.example.json to avoid pointing live tests at placeholder configs.

An example minimal job persistence configuration:

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

2. Choose a runtime

You can run ProxmoxMCP-Plus directly from PyPI:

uvx proxmox-mcp-plus

Or install it first:

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

Alternatively, use Docker with environment variables and volume mounts for configuration:

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

For native MCP Streamable HTTP mode:

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 \
  -v "$(pwd)/proxmox-config/config.json:/app/proxmox-config/config.json:ro" \
  ghcr.io/rekklesna/proxmoxmcp-plus:latest

Point MCP clients to http://<host>:8000/mcp for Streamable HTTP mode.

who should consider ProxmoxMCP-Plus

This tool is aimed at Proxmox administrators and developers who want a Python-based interface to the MCP protocol for more advanced or customized management workflows. Its configurable nature and support for multiple deployment options make it a good fit for homelabs, test environments, or specialized production setups where the REST API is not enough.

Be aware that this project assumes familiarity with Proxmox API concepts and requires manual editing of JSON configuration files, which might be less convenient than integrated GUI tools. The default SQLite for job persistence is fine for smaller setups but may not scale.

Overall, ProxmoxMCP-Plus fills a niche for those needing deep protocol-level interaction with Proxmox VE and who prefer Python tooling. It’s a solid starting point for building custom automation around Proxmox MCP, with a clean and pragmatic codebase.

→ GitHub Repo: RekklesNA/ProxmoxMCP-Plus ⭐ 206 · Python