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