Initial commit: Custom Proxmox MCP with SSE wrapper

README.md

@@ -0,0 +1,69 @@
+# 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).
+
+## Local Development
+
+Prerequisites: Docker
+
+```bash
+# 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.