Custom Proxmox MCP Server

A robust, maintenance-free Model Context Protocol (MCP) server for Proxmox VE, built with Python and proxmoxer.

Philosophy: The Hybrid Approach

Most MCP servers suffer from "feature rot" where the author implements 10 tools (start_vm, stop_vm) but misses 500 others. This project takes a hybrid approach:

Core Tools: A small set of high-value tools for discovery and context.
Raw API Access: A single powerful tool proxmox_api that allows the LLM to call any Proxmox API endpoint dynamically. This ensures 100% API coverage without writing wrappers for every function.

Tools

`list_nodes`

Returns a list of all nodes in the cluster with their status.

`get_cluster_resources`

Returns a summary of all resources (VMs, LXC containers, storage) across the cluster.

`proxmox_api_call`

Executes a raw API call to Proxmox.

path: API path (e.g., nodes/pve1/qemu/100/status/start).
method: HTTP method (GET, POST, PUT, DELETE).
data: Optional JSON payload for POST/PUT requests.

Configuration

Environment Variables:

Variable	Required	Description	Example
`PROXMOX_URL`	Yes	Proxmox host and port (no `https://`)	`pve.local.example.io:8006`
`PROXMOX_USER`	Yes	Full `user@realm` format	`proxmox-mcp@pam`
`PROXMOX_TOKEN_ID`	Yes*	Token name only (not full ID)	`token`
`PROXMOX_PASSWORD`	Yes	Token secret or password	`xxxxxxxx-xxxx-...`
`PROXMOX_VERIFY_SSL`	No	SSL verification (default: `false`)	`false`
`MCP_ALLOWED_HOSTS`	No	Allowed Host headers for reverse proxy	`mcp.example.io,localhost:*`

Note: If your full token is proxmox-mcp@pam!mytoken, set PROXMOX_USER=proxmox-mcp@pam and PROXMOX_TOKEN_ID=mytoken.

Deployment

Docker Compose

services:
  proxmox-mcp:
    image: gitea.ext.ben.io/b3nw/proxmox-mcp-custom:latest
    environment:
      - PROXMOX_URL=pve.local.example.io:8006
      - PROXMOX_USER=proxmox-mcp@pam
      - PROXMOX_TOKEN_ID=token
      - PROXMOX_PASSWORD=your-token-secret
      - PROXMOX_VERIFY_SSL=false
      - MCP_ALLOWED_HOSTS=proxmox-mcp.example.io,localhost:*
    ports:
      - "8000:8000"
    restart: unless-stopped

MCP Client Configuration

Connect via SSE endpoint: https://your-host/sse

Local Development

# Setup
cp .env.example .env
# Edit .env with your Proxmox credentials

# Build and run
make build
make dev

# Test
make logs      # View container logs
make test-sse  # Test SSE endpoint

# Cleanup
make stop

Tech Stack

Language: Python 3.11+
MCP SDK: mcp with FastMCP
Proxmox Client: proxmoxer
Transport: SSE (Server-Sent Events)
Server: uvicorn (ASGI)

2.7 KiB Raw Blame History