proxmox-mcp

Give Claude (and any other LLM agent) hands on your Proxmox VE cluster. A small, dependency-light Model Context Protocol server that turns cluster status, VM/container lifecycle, and node control into first-class tools.

Ask "is anything down in my cluster?" and get a real answer. Say "restart the pihole container" and it happens — with a task UPID you can follow to completion. No SSH gymnastics, no hand-crafted API tokens in your shell history.

What it does

The server exposes eight tools over MCP, split into read and write:

Read

• proxmox_status — Full cluster snapshot: nodes (CPU/RAM), running vs. stopped VMs and containers, and storage pools with a warning at ≥85% usage.
• proxmox_find — Locate a VM or container by name (partial match) and get its vmid, node, and type — the details you need before acting on it.
• proxmox_task_status — Follow a running or finished Proxmox task by its UPID, including the last log lines and exit status.

Write

• proxmox_vm_action — Lifecycle control for a VM: start, stop, shutdown, reset, suspend, resume.
• proxmox_container_action — Lifecycle control for an LXC container: start, stop, shutdown, reboot, suspend, resume.
• proxmox_node_action — reboot or shutdown a node.
• proxmox_delete_vm — Permanently delete a stopped VM.
• proxmox_delete_container — Permanently delete a stopped container.

Every write returns a task UPID so the agent can verify the outcome with proxmox_task_status.

Install

The console script proxmox-mcp starts the server over stdio.

pipx (isolated, recommended for a global install)

pipx install git+https://github.com/ManciDRaffy/proxmox-mcp.git

uv

uv tool install git+https://github.com/ManciDRaffy/proxmox-mcp.git

pip, from source

git clone https://github.com/ManciDRaffy/proxmox-mcp.git
cd proxmox-mcp
pip install .

Configure

All configuration comes from environment variables — there are no host-specific defaults baked into the code. Copy .env.example to .env, or export them directly.

Variable	Required	Default	Description
PROXMOX_API_URL	Yes	—	Base URL of the Proxmox VE API, including the port, e.g. https://proxmox.example.com:8006.
PROXMOX_TOKEN	Yes	—	API token in the form user@realm!tokenid=uuid.
PROXMOX_VERIFY_SSL	No	true	Set to false to skip TLS verification (self-signed certs). Any other value keeps it on.
PROXMOX_CLUSTER_CACHE_SECONDS	No	30	TTL for cached cluster snapshots. 0 disables caching.

Creating a token: in the Proxmox web UI go to Datacenter → Permissions → API Tokens, add a token for a user, and give that user the roles it needs (PVEAuditor for read-only; add PVEVMAdmin for lifecycle actions). The token string has the exact shape user@realm!tokenid=uuid — for example root@pam!mcp=00000000-0000-0000-0000-000000000000.

Use with Claude Desktop

Add the server to your claude_desktop_config.json (on macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "proxmox": {
      "command": "proxmox-mcp",
      "env": {
        "PROXMOX_API_URL": "https://proxmox.example.com:8006",
        "PROXMOX_TOKEN": "root@pam!mcp=00000000-0000-0000-0000-000000000000",
        "PROXMOX_VERIFY_SSL": "true",
        "PROXMOX_CLUSTER_CACHE_SECONDS": "30"
      }
    }
  }
}

Restart Claude Desktop and the eight proxmox_* tools appear. If proxmox-mcp is not on Claude's PATH, use its absolute path (find it with which proxmox-mcp) or run it via your tool manager, e.g. "command": "uv", "args": ["tool", "run", "proxmox-mcp"].

Security

• Read vs. write. Three tools are strictly read-only (proxmox_status, proxmox_find, proxmox_task_status). The rest change cluster state, and two of them (proxmox_delete_vm, proxmox_delete_container) are destructive and irreversible. Scope your API token to exactly what you want the agent to do — a PVEAuditor-only token makes the whole server safely read-only.
• PROXMOX_VERIFY_SSL. TLS verification is on by default. Only set it to false for clusters using self-signed certificates, and prefer installing your CA over disabling verification.
• Credentials. The token is read from the environment and never logged. Keep your .env out of version control (it is already in .gitignore) and never commit real tokens.
• Least privilege. Give the token's user only the roles required for the actions you intend to allow, and remember that lifecycle and delete actions run with whatever permissions that user holds.

License

MIT — see LICENSE. Copyright (c) 2026 Marcel Kummerow.