proxmox-mcp-custom/IMPLEMENTATION.md

Implementation Details

Technical documentation for the Proxmox MCP Server.

Architecture

┌─────────────────────────────────────────────────────────┐
│                    MCP Client (Gemini CLI)              │
└─────────────────────────┬───────────────────────────────┘
                          │ SSE
                          ▼
┌─────────────────────────────────────────────────────────┐
│              Docker Container (proxmox-mcp)             │
│  ┌───────────────────────────────────────────────────┐  │
│  │              FastMCP + uvicorn (:8000)            │  │
│  └───────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────┐  │
│  │                  ClusterManager                   │  │
│  │    ┌─────────┐  ┌─────────┐  ┌─────────┐         │  │
│  │    │ prod    │  │ homelab │  │  ...    │         │  │
│  │    └────┬────┘  └────┬────┘  └────┬────┘         │  │
│  └─────────┼────────────┼────────────┼──────────────┘  │
└────────────┼────────────┼────────────┼──────────────────┘
             │            │            │
             ▼            ▼            ▼
      ┌──────────┐  ┌──────────┐  ┌──────────┐
      │ Proxmox  │  │ Proxmox  │  │ Proxmox  │
      │ Cluster 1│  │ Cluster 2│  │ Cluster N│
      └──────────┘  └──────────┘  └──────────┘

Components

ClusterManager

• Loads cluster configs from clusters.json
• Maintains ProxmoxAPI connections for each cluster
• Handles cluster selection logic (default if single cluster)

Transport Security

• TransportSecuritySettings validates Host headers
• Configurable via MCP_ALLOWED_HOSTS

Tool Strategy

Layer 1: Curated Tools

• list_clusters() - Discovery
• list_nodes(cluster) - Node status
• get_cluster_resources(cluster) - Resource summary

Layer 2: Raw Access

• proxmox_api_call(cluster, path, method, data) - Any API endpoint

Configuration Format

{
  "clusters": {
    "<name>": {
      "url": "host:port",
      "user": "user@realm",
      "token_id": "token_name",
      "token_secret": "secret",
      "verify_ssl": false
    }
  }
}

Token Authentication

The proxmoxer library uses:

Authorization: PVEAPIToken={user}!{token_id}={token_secret}

So for token mcp@pam!mytoken:

• user = mcp@pam
• token_id = mytoken

Build & Deploy

• Build: uv + multi-stage Docker
• Registry: Gitea Container Registry
• CI/CD: Gitea Actions
• Deploy: Docker Compose / Portainer