Proxmox Homelab FastMCP
Allows checking Docker container health and status inside LXC containers via pct exec.
Provides tools for managing Proxmox VE nodes and LXC containers, including cluster status, container lifecycle operations, snapshots, and service inspection.
Provides Tailscale mesh diagnostics, including node reachability, Tailscale IPs, and peer online status.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Proxmox Homelab FastMCP check cluster status and list all LXC containers"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| Returns node specs, CPU load, RAM usage %, and storage availability. |
| Lists all LXC containers with VMID, name, status, and resource consumption. |
| Retrieves deep config and network details for a specific VMID. |
| Executes |
| Creates a snapshot with custom name and description. |
| Inspects systemd or docker container status inside an LXC. |
| Inspects the local Tailscale mesh network status and peer devices. |
Architecture & Requirements
Python:
>= 3.11FastMCP:
>= 0.4.0Pydantic:
>= 2.0.0Host Connectivity: Passwordless SSH key authentication from the MCP host to the Proxmox host (
pvesh).
Environment Variables
Variable | Default | Description |
|
| Proxmox VE node IP or hostname |
|
| SSH user |
|
| Private SSH key path |
|
| 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 syncRun in stdio mode (default):
uv run python -m proxmox_homelab_mcp.serverOr run in SSE transport mode:
uv run python -m proxmox_homelab_mcp.server --transport sse --port 8770MCP 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: trueClaude 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 toolslxc_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
Scored across 7 tools
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.
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.
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.
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
Manage Vozora VPS servers, SSH keys, firewalls, DNS and usage from an AI agent.
Provides capabilities that let LLM agents perform a range of infrastructure management tasks.
Manage NodePal Minecraft servers, worlds, mods, backups and console from AI agents.
Manage VeriTeknik servers, DNS, backups and support tickets from your AI assistant.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage Proxmox VE infrastructure, including VMs, containers, storage, and cluster operations via natural language.MIT
- AlicenseBqualityDmaintenanceEnables AI assistants to manage Proxmox VE infrastructure, including VMs, containers, storage, network, high availability, replication, SDN, and node administration.10017 npmMIT
- AlicenseAqualityBmaintenanceEnables natural language interaction with Proxmox VE clusters for managing VMs, containers, storage, and snapshots.2711 npm3MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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.5Apache 2.0