Ben
2bb507cdac
All checks were successful
Build and Push Proxmox MCP Docker Image / build (push) Successful in 7s
91 lines
2.7 KiB
Markdown
91 lines
2.7 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.
|
|
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.
|
|
|
|
## Tools
|
|
|
|
### `list_nodes`
|
|
Returns a list of all nodes in the cluster with their status.
|
|
|
|
### `get_cluster_resources`
|
|
Returns a summary of all resources (VMs, LXC containers, storage) across the cluster.
|
|
|
|
### `proxmox_api_call`
|
|
Executes a raw API call to Proxmox.
|
|
* `path`: API path (e.g., `nodes/pve1/qemu/100/status/start`).
|
|
* `method`: HTTP method (GET, POST, PUT, DELETE).
|
|
* `data`: Optional JSON payload for POST/PUT requests.
|
|
|
|
## Configuration
|
|
|
|
Environment Variables:
|
|
|
|
| Variable | Required | Description | Example |
|
|
|----------|----------|-------------|---------|
|
|
| `PROXMOX_URL` | Yes | Proxmox host and port (no `https://`) | `pve.local.example.io:8006` |
|
|
| `PROXMOX_USER` | Yes | Full `user@realm` format | `proxmox-mcp@pam` |
|
|
| `PROXMOX_TOKEN_ID` | Yes* | Token name only (not full ID) | `token` |
|
|
| `PROXMOX_PASSWORD` | Yes | Token secret or password | `xxxxxxxx-xxxx-...` |
|
|
| `PROXMOX_VERIFY_SSL` | No | SSL verification (default: `false`) | `false` |
|
|
| `MCP_ALLOWED_HOSTS` | No | Allowed Host headers for reverse proxy | `mcp.example.io,localhost:*` |
|
|
|
|
> **Note:** If your full token is `proxmox-mcp@pam!mytoken`, set `PROXMOX_USER=proxmox-mcp@pam` and `PROXMOX_TOKEN_ID=mytoken`.
|
|
|
|
## Deployment
|
|
|
|
### Docker Compose
|
|
|
|
```yaml
|
|
services:
|
|
proxmox-mcp:
|
|
image: gitea.ext.ben.io/b3nw/proxmox-mcp-custom:latest
|
|
environment:
|
|
- PROXMOX_URL=pve.local.example.io:8006
|
|
- PROXMOX_USER=proxmox-mcp@pam
|
|
- PROXMOX_TOKEN_ID=token
|
|
- PROXMOX_PASSWORD=your-token-secret
|
|
- PROXMOX_VERIFY_SSL=false
|
|
- MCP_ALLOWED_HOSTS=proxmox-mcp.example.io,localhost:*
|
|
ports:
|
|
- "8000:8000"
|
|
restart: unless-stopped
|
|
```
|
|
|
|
### MCP Client Configuration
|
|
|
|
Connect via SSE endpoint: `https://your-host/sse`
|
|
|
|
## Local Development
|
|
|
|
```bash
|
|
# Setup
|
|
cp .env.example .env
|
|
# Edit .env with your Proxmox credentials
|
|
|
|
# Build and run
|
|
make build
|
|
make dev
|
|
|
|
# Test
|
|
make logs # View container logs
|
|
make test-sse # Test SSE endpoint
|
|
|
|
# Cleanup
|
|
make stop
|
|
```
|
|
|
|
## Tech Stack
|
|
|
|
* **Language:** Python 3.11+
|
|
* **MCP SDK:** `mcp` with `FastMCP`
|
|
* **Proxmox Client:** `proxmoxer`
|
|
* **Transport:** SSE (Server-Sent Events)
|
|
* **Server:** `uvicorn` (ASGI)
|