Ben
9c7e2d41dc
All checks were successful
Build and Push Proxmox MCP Docker Image / build (push) Successful in 7s
70 lines
2.2 KiB
Markdown
70 lines
2.2 KiB
Markdown
# 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.
|