proxmox-mcp-custom/README.md

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:

1. Core Tools: A small set of high-value tools for discovery and context (e.g., list_nodes, get_cluster_resources).
2. 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).

Build & Deploy

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