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
    environment:
      - MCP_ALLOWED_HOSTS=proxmox-mcp.example.io,localhost:*
    volumes:
      - ./clusters.json:/app/clusters.json:ro
    ports:
      - "8000:8000"
    restart: unless-stopped

3. Connect MCP Client

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

Environment Variables

Variable	Default	Description
`MCP_ALLOWED_HOSTS`	`localhost:,127.0.0.1:`	Allowed Host headers
`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
make test-sse
make stop

Tech Stack

Python 3.11+ / FastMCP / proxmoxer
SSE transport / uvicorn
Docker with multi-stage build

2.3 KiB Raw Blame History