Proxmox MCP — Claude Code MCP server for Proxmox VE
Wires an AI assistant into the Proxmox VE API so it can read clusters, nodes, storage, containers and VMs. Useful when clicking through the web UI gets old.
claude mcp add proxmox-mcp-is-an-opinionated-mcp-server -- docker run -i --rm ghcr.io/sergelogvinov/proxmox-mcp:v0.3.0What Proxmox MCP is an opinionated MCP server does
The server links an MCP client to the Proxmox VE API and handles more than one cluster at a time, returning structured data. Every tool starts out read-only: proxmox_clusters_list, proxmox_clusters_describe, proxmox_nodes_list, proxmox_nodes_describe, proxmox_storage_list, proxmox_storage_describe, proxmox_vms_list, proxmox_vms_describe, proxmox_containers_list, proxmox_containers_describe, proxmox_events_list. Call proxmox_clusters_list first, since the other tools take a cluster name from it.
Backups and reboots stay off until you pass --allow-destructive, which adds proxmox_vms_backup and proxmox_containers_backup. Those kick off an asynchronous job and hand back its Proxmox task identifier; a created task is not a finished backup. The server does not take over infrastructure changes — Terraform, Ansible and GitOps keep that job.
You need a YAML file listing your clusters before anything runs. Each entry requires region and a url ending in /api2/json, plus either a token (token_id and token_secret, or the file variants) or a username and password pair. Pick one login method per cluster, not both. Point the server at the file with --config or the CONFIG_FILE variable. The HTTP endpoint ships without user authentication, so access control rests on Proxmox tokens sent in an Authorization header.
What it helps with
- check node and cluster health without opening the web UI
- pull a list of LXC containers with their resource usage
- see how full each storage pool is and what type it is
- scan recent Proxmox tasks across all nodes
- gather facts before touching the infrastructure
Example prompts for the agent
- List my Proxmox clusters and the node status in homelab
- Which VMs are running right now and how much are they using?
- Show the latest tasks for the homelab cluster
How to install Proxmox MCP is an opinionated MCP server
Platform CLI
claude mcp add proxmox-mcp-is-an-opinionated-mcp-server -- docker run -i --rm ghcr.io/sergelogvinov/proxmox-mcp:v0.3.0Platform CLI
codex mcp add proxmox-mcp-is-an-opinionated-mcp-server -- docker run -i --rm ghcr.io/sergelogvinov/proxmox-mcp:v0.3.0Config file
{
"mcpServers": {
"proxmox-mcp-is-an-opinionated-mcp-server": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/sergelogvinov/proxmox-mcp:v0.3.0"
]
}
}
}Config file
{
"servers": {
"proxmox-mcp-is-an-opinionated-mcp-server": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/sergelogvinov/proxmox-mcp:v0.3.0"
]
}
}
}Platform CLI
gemini mcp add proxmox-mcp-is-an-opinionated-mcp-server docker run -i --rm ghcr.io/sergelogvinov/proxmox-mcp:v0.3.0Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Proxmox MCP is an opinionated MCP server
How do I install Proxmox MCP in Claude Code?
Run claude mcp add proxmox-mcp-is-an-opinionated-mcp-server -- docker run -i --rm ghcr.io/sergelogvinov/proxmox-mcp:v0.3.0. A local install without Docker is available as brew install sergelogvinov/tap/proxmox-mcp.
What does Proxmox MCP do?
It gives an AI assistant access to the Proxmox VE API: lists and details for clusters, nodes, storage, containers and virtual machines, plus recent task events. All tools are read-only by default.
How do I enable backups and reboots?
Start the server with --allow-destructive to get proxmox_vms_backup and proxmox_containers_backup. They start an asynchronous task and return its identifier rather than a completion result.
