# Proxmox Homelab FastMCP

A fast, lightweight Model Context Protocol (MCP) server built with **FastMCP** to manage Proxmox VE nodes, LXC containers, system services, and Tailscale mesh status directly from AI agent workflows (Hermes, Claude Code, Cursor, Windsurf).

## Features

- 🖥️ **Cluster & Node Metrics:** Real-time CPU model, cores, RAM usage, swap, load averages, and rootfs storage from Proxmox VE.
- 📦 **LXC Container Lifecycle:** Query running/stopped LXCs, inspect detailed CPU/RAM/Disk allocations, and trigger power actions (`start`, `stop`, `shutdown`, `reboot`).
- 📸 **Automated Snapshots:** Create point-in-time container snapshots before migrations or dangerous operations.
- 🐳 **Service & Container Inspection:** Check systemd units and docker container health inside any LXC (`pct exec`).
- 🌐 **Tailscale Mesh Diagnostics:** Query node reachability, Tailscale IPs, and peer online status.

---

## Available MCP Tools

| Tool Name | Description |
|---|---|
| `proxmox_cluster_status` | Returns node specs, CPU load, RAM usage %, and storage availability. |
| `lxc_list` | Lists all LXC containers with VMID, name, status, and resource consumption. |
| `lxc_get_info` | Retrieves deep config and network details for a specific VMID. |
| `lxc_control_power` | Executes `start`, `stop`, `shutdown`, or `reboot` on an LXC container. |
| `lxc_snapshot_create` | Creates a snapshot with custom name and description. |
| `lxc_service_status` | Inspects systemd or docker container status inside an LXC. |
| `tailscale_mesh_status` | Inspects the local Tailscale mesh network status and peer devices. |

---

## Architecture & Requirements

- **Python:** `>= 3.11`
- **FastMCP:** `>= 0.4.0`
- **Pydantic:** `>= 2.0.0`
- **Host Connectivity:** Passwordless SSH key authentication from the MCP host to the Proxmox host (`pvesh`).

### Environment Variables

| Variable | Default | Description |
|---|---|---|
| `PROXMOX_HOST` | `192.168.0.27` | Proxmox VE node IP or hostname |
| `PROXMOX_USER` | `root` | SSH user |
| `PROXMOX_SSH_KEY` | `~/.ssh/id_rsa` | Private SSH key path |
| `PROXMOX_NODE` | `homelab` | Proxmox VE node name |

---

## Installation & Setup

### 1. Standalone via `uv`

```bash
git clone https://github.com/mpandudc/proxmox-homelab-mcp.git
cd proxmox-homelab-mcp
uv sync
```

Run in stdio mode (default):
```bash
uv run python -m proxmox_homelab_mcp.server
```

Or run in SSE transport mode:
```bash
uv run python -m proxmox_homelab_mcp.server --transport sse --port 8770
```

---

## MCP Client Configuration

### Hermes Agent (`~/.hermes/config.yaml`)

```yaml
mcp_servers:
  proxmox:
    command: /path/to/proxmox-homelab-mcp/.venv/bin/python
    args:
      - -m
      - proxmox_homelab_mcp.server
    env:
      PYTHONPATH: /path/to/proxmox-homelab-mcp/src
      PROXMOX_HOST: "192.168.0.27"
      PROXMOX_USER: "root"
      PROXMOX_NODE: "homelab"
    enabled: true
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "proxmox": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/proxmox-homelab-mcp",
        "run",
        "proxmox-homelab-mcp"
      ],
      "env": {
        "PROXMOX_HOST": "192.168.0.27",
        "PROXMOX_USER": "root",
        "PROXMOX_NODE": "homelab"
      }
    }
  }
}
```

---

## License

MIT License © 2026 Muhammad Pandu Dwi Cahyo.