Custom Proxmox MCP Server

A robust, maintenance-free Model Context Protocol (MCP) server for Proxmox VE with multi-cluster support.

Features

• Multi-Cluster: Manage multiple Proxmox clusters from a single container
• Hybrid Approach: Curated high-level tools + raw API access for 100% coverage
• Zero Maintenance: Raw API tool works with any Proxmox feature without code changes

Tools

Tool	Description
list_clusters	Lists all configured Proxmox clusters
list_nodes	Lists nodes in a cluster
get_cluster_resources	Gets VMs, LXCs, and storage summary
proxmox_api_call	Execute any Proxmox API call directly

All tools accept a cluster parameter. If only one cluster is configured, it's optional.

Configuration

1. Create clusters.json

{
  "clusters": {
    "production": {
      "url": "pve-prod.example.io:8006",
      "user": "mcp@pam",
      "token_id": "token",
      "token_secret": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "verify_ssl": false
    },
    "homelab": {
      "url": "pve-home.local:8006",
      "user": "root@pam",
      "token_id": "mcp",
      "token_secret": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
      "verify_ssl": false
    }
  }
}

Token Format: If your full token is user@pam!mytoken, set user: "user@pam" and token_id: "mytoken"

2. Deploy with Docker Compose

services:
  proxmox-mcp:
    image: gitea.ext.ben.io/b3nw/proxmox-mcp-custom:latest
    volumes:
      - ./clusters.json:/app/clusters.json:ro
    ports:
      - "8000:8000"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
    restart: unless-stopped

3. Connect MCP Client

MCP endpoint: https://your-host/mcp

Endpoints

Endpoint	Description
/mcp	MCP HTTP endpoint
/health	Health check endpoint for Docker/load balancers

The /health endpoint returns {"status": "ok"} (or {"status": "degraded"} if no clusters are configured) and is designed for Docker health checks.

Environment Variables

Variable	Default	Description
CLUSTERS_CONFIG_PATH	/app/clusters.json	Path to clusters config

Local Development

# Setup
cp clusters.json.example clusters.json
# Edit clusters.json with your credentials

# Build and run
make build
make dev

# Test
make logs
curl http://localhost:8001/health
make stop

Tech Stack

• Python 3.11+ / FastMCP 2.0+ / proxmoxer
• HTTP transport / uvicorn
• Docker with multi-stage build