Ben
4b576d40ad
All checks were successful
Build and Push Proxmox MCP Docker Image / build (push) Successful in 8s
97 lines
2.3 KiB
Markdown
97 lines
2.3 KiB
Markdown
# Custom Proxmox MCP Server
|
|
|
|
A robust, maintenance-free Model Context Protocol (MCP) server for Proxmox VE with **multi-cluster support**.
|
|
|
|
## Features
|
|
|
|
- **Multi-Cluster:** Manage multiple Proxmox clusters from a single container
|
|
- **Hybrid Approach:** Curated high-level tools + raw API access for 100% coverage
|
|
- **Zero Maintenance:** Raw API tool works with any Proxmox feature without code changes
|
|
|
|
## Tools
|
|
|
|
| Tool | Description |
|
|
|------|-------------|
|
|
| `list_clusters` | Lists all configured Proxmox clusters |
|
|
| `list_nodes` | Lists nodes in a cluster |
|
|
| `get_cluster_resources` | Gets VMs, LXCs, and storage summary |
|
|
| `proxmox_api_call` | Execute any Proxmox API call directly |
|
|
|
|
All tools accept a `cluster` parameter. If only one cluster is configured, it's optional.
|
|
|
|
## Configuration
|
|
|
|
### 1. Create `clusters.json`
|
|
|
|
```json
|
|
{
|
|
"clusters": {
|
|
"production": {
|
|
"url": "pve-prod.example.io:8006",
|
|
"user": "mcp@pam",
|
|
"token_id": "token",
|
|
"token_secret": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
|
|
"verify_ssl": false
|
|
},
|
|
"homelab": {
|
|
"url": "pve-home.local:8006",
|
|
"user": "root@pam",
|
|
"token_id": "mcp",
|
|
"token_secret": "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy",
|
|
"verify_ssl": false
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
> **Token Format:** If your full token is `user@pam!mytoken`, set `user: "user@pam"` and `token_id: "mytoken"`
|
|
|
|
### 2. Deploy with Docker Compose
|
|
|
|
```yaml
|
|
services:
|
|
proxmox-mcp:
|
|
image: gitea.ext.ben.io/b3nw/proxmox-mcp-custom:latest
|
|
environment:
|
|
- MCP_ALLOWED_HOSTS=proxmox-mcp.example.io,localhost:*
|
|
volumes:
|
|
- ./clusters.json:/app/clusters.json:ro
|
|
ports:
|
|
- "8000:8000"
|
|
restart: unless-stopped
|
|
```
|
|
|
|
### 3. Connect MCP Client
|
|
|
|
SSE endpoint: `https://your-host/sse`
|
|
|
|
## Environment Variables
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `MCP_ALLOWED_HOSTS` | `localhost:*,127.0.0.1:*` | Allowed Host headers |
|
|
| `CLUSTERS_CONFIG_PATH` | `/app/clusters.json` | Path to clusters config |
|
|
|
|
## Local Development
|
|
|
|
```bash
|
|
# Setup
|
|
cp clusters.json.example clusters.json
|
|
# Edit clusters.json with your credentials
|
|
|
|
# Build and run
|
|
make build
|
|
make dev
|
|
|
|
# Test
|
|
make logs
|
|
make test-sse
|
|
make stop
|
|
```
|
|
|
|
## Tech Stack
|
|
|
|
- Python 3.11+ / FastMCP / proxmoxer
|
|
- SSE transport / uvicorn
|
|
- Docker with multi-stage build
|