ahmetem

Homelab Proxmox MCP — Development skill for Claude Code

Development community

Local MCP server for managing Proxmox VE clusters from Claude Desktop.

How to install Homelab Proxmox MCP

This entry records only its repository, not the path inside it, so there is no exact command to give. Open ahmetem/homelab-proxmox-mcp and copy the folder into ~/.claude/skills/, or the file into ~/.claude/agents/.

What Homelab Proxmox MCP does

Local MCP server for managing Proxmox VE clusters from Claude Desktop. Token-auth, 15 tools, GPL v3.

Alternatives in Development

Doctor — Environment diagnostics with interactive fixes — providers, auth, RTK, hooks, token optimization 2.8k ★
Gmail AutoAuth MCP Installation Guide — This guide will help you install and configure the Gmail AutoAuth MCP server for managing Gmail operations thr 1.1k ★
Premiere Pro MCP — Adobe Premiere Pro MCP — independent, local-first server for supported workflows 292 ★

README

Proxmox MCP Server

A local [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that lets Claude Desktop (or any MCP-compatible client) manage a **Proxmox VE** cluster through its REST API using token authentication.

Tested with **Proxmox VE 9.1.9** on a single-node setup. Multi-node clusters should work — every tool accepts a `node` parameter.

🇹🇷 Türkçe README için: [README.tr.md](./README.tr.md)

Features

The package exposes **52 tools**, grouped by category below. Read-only tools are safe to call automatically; every state-changing tool requires `confirm=true`, and tools that destroy persistent data additionally require `i_understand_data_loss=true` (see **Built-in safety**).

Token-efficiency features (v1.0):

proxmox_health_overview answers "how is the server?" in one call.
List filters — e.g. proxmox_list_vms(status='running', node=...), proxmox_list_backups(vmid=...) — return only what you asked for.
fields projection — with response_format='json', pass fields=['vmid','name','status'] to strip every other key.
wait_seconds on task-launching tools (power, snapshot, backup, restore, clone, move-disk, LVM/ZFS provisioning): the tool polls the Proxmox task and returns the final result inline, saving a follow-up status call.
JSON output is compact and hard-capped; oversized lists are truncated at the item level and stay valid JSON ({"_truncated_items": N} marker).

Overview & nodes (read-only)

Tool	Description
`proxmox_health_overview`	One-call summary: node load, guest states, storage fill levels, ZFS pool health
`proxmox_list_nodes`	List all nodes in the cluster with status, uptime, CPU and memory usage
`proxmox_get_node_status`	Detailed status for one node: CPU model, kernel, load average, disk, swap