# 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.