Skip to main content
Glama
Proxmox Homelab FastMCP

Proxmox Homelab FastMCP

by mpandudc

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-mcps

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.

Available Tools

7 tools
lxc_control_powerLxc Control PowerA

Manage LXC power lifecycle: 'start', 'stop', 'shutdown', or 'reboot'.

Inputs: vmid (required), action (required). Returns: object

lxc_get_infoLxc Get InfoA

Get detailed configuration and runtime state for a specific LXC container.

Inputs: vmid (required). Returns: object

lxc_listLxc ListA

List all LXC containers with VMID, name, status (running/stopped), CPU, RAM, and Disk metrics.

Inputs: no named parameters. Returns: result

lxc_service_statusLxc Service StatusB

Inspect systemd service or docker container status inside an LXC via pct exec.

Inputs: vmid (required), service_name (required). Returns: object

lxc_snapshot_createLxc Snapshot CreateB

Create a point-in-time snapshot of an LXC before deployments or maintenance.

Inputs: vmid (required), snapname (required), description. Returns: object

proxmox_cluster_statusProxmox Cluster StatusA

Get high-level host node status: CPU model, cores, RAM usage, swap, loadavg, and uptime.

Inputs: no named parameters. Returns: object

tailscale_mesh_statusTailscale Mesh StatusA

Inspect the local Tailscale mesh network status and peer devices.

Inputs: no named parameters. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action: host node status, LXC list vs detail, in-container service status, power control, snapshots, and Tailscale network status. Even the 'status' tools are cleanly separated by the resource prefix.

    Naming Consistency3/5

    Names are readable but mix conventions: lxc_list and lxc_get_info use verb-first patterns, lxc_snapshot_create uses noun-verb, and the 'status' tools use noun_status. The inconsistent placement of verbs (control_power vs snapshot_create) is the main issue.

    Tool Count5/5

    7 tools is well-scoped for a homelab management server covering host status, LXC operations, and network status. Each tool has a clear purpose with no redundant bloat.

    Completeness3/5

    The set covers common read and control operations: list, inspect, power, snapshot, service check, plus host and network status. However, it lacks LXC create/delete/config updates, snapshot restore/list/delete, and any VM management, leaving notable gaps for a Proxmox homelab tool.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to manage Proxmox VE infrastructure, including VMs, containers, storage, and cluster operations via natural language.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants and automation agents to inspect Proxmox clusters, nodes, storage, containers, VMs, and recent events through the Proxmox VE API, with optional backup actions.
      5
      Apache 2.0