Skip to main content
Glama
mpandudc

Proxmox Homelab FastMCP

by mpandudc
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

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.

Related MCP server: Proxmox MCP Server

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

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

Run in stdio mode (default):

uv run python -m proxmox_homelab_mcp.server

Or run in SSE transport mode:

uv run python -m proxmox_homelab_mcp.server --transport sse --port 8770

MCP Client Configuration

Hermes Agent (~/.hermes/config.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)

{
  "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.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers