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 (e.g., list_nodes, get_cluster_resources).
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.

Tech Stack

Language: Python 3.11+
MCP SDK: mcp (Official Python SDK) with FastMCP (if available) or standard server implementation.
Proxmox Client: proxmoxer (Community standard, stable).
Transport: SSE (Server-Sent Events) for Docker/Remote compatibility.
Deployment: Docker (built via Gitea Actions).

Tools

`list_nodes`

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

`get_resources`

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

`proxmox_api`

Executes a raw API call to Proxmox.

service: Service path (e.g., nodes/pve1/qemu).
method: HTTP Method (GET, POST, PUT, DELETE).
data: Optional JSON payload.

Configuration

Required Environment Variables:

PROXMOX_URL: Base URL (e.g., https://192.168.1.1:8006).
PROXMOX_USER: User (e.g., root@pam).
PROXMOX_PASSWORD: Password or Token Secret.
PROXMOX_TOKEN_ID: (Optional) Token ID if using tokens (e.g., mcp-token).
PROXMOX_VERIFY_SSL: true or false (Default: false for homelabs).

Local Development

Prerequisites: Docker

# 1. Copy and configure credentials
cp .env.example .env
# Edit .env with your Proxmox credentials

# 2. Build and start the server
make build
make dev

# 3. View logs
make logs

# 4. Test SSE endpoint (5s timeout)
make test-sse

# 5. Stop when done
make stop

Build & Deploy

This project is built using Gitea Actions and pushed to the internal registry. Deploy using Portainer.

2.2 KiB Raw Blame History