Skip to main content
Glama
proxmox-mcp

proxmox-mcp

by ManciDRaffy

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.

Python License: MIT MCP

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.

Related MCP server: proxmox-mcp-server

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.

Available Tools

8 tools
proxmox_container_actionB

Run a lifecycle action on a container. action: start | stop | shutdown | reboot | suspend | resume

Inputs: node (required), vmid (required), action (required). Returns: result

proxmox_delete_containerA

Permanently delete a container (the container must be stopped first). Returns the task UPID — use proxmox_task_status to check whether it finished.

Inputs: node (required), vmid (required). Returns: result

proxmox_delete_vmA

Permanently delete a VM (the VM must be stopped first). Returns the task UPID — use proxmox_task_status to check whether it finished.

Inputs: node (required), vmid (required). Returns: result

proxmox_findA

Find a VM or container by name (partial matches are supported). Returns the vmid, node, and type — useful before running admin actions.

Inputs: name (required). Returns: result

proxmox_node_actionC

Run an action on a Proxmox node. action: reboot | shutdown

Inputs: node (required), action (required). Returns: result

proxmox_statusA

Return the current state of the Proxmox cluster: nodes, VMs, containers, and storage.

Inputs: no named parameters. Returns: result

proxmox_task_statusB

Check the status of a running or completed Proxmox task by its UPID.

Inputs: node (required), upid (required). Returns: result

proxmox_vm_actionB

Run a lifecycle action on a VM. action: start | stop | shutdown | reset | suspend | resume

Inputs: node (required), vmid (required), action (required). Returns: result

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 8 tools

    Disambiguation5/5

    Each tool targets a distinct resource (container, VM, node, cluster status) or action (delete, find, task status). No overlap in purpose.

    Naming Consistency4/5

    All tool names start with 'proxmox_', but the second part varies between 'noun_action' (container_action, vm_action), 'delete_noun' (delete_container), and standalone nouns (status, find). Mostly consistent with minor deviations.

    Tool Count5/5

    8 tools cover core lifecycle actions, deletion, finding, and cluster status without being excessive or sparse.

    Completeness3/5

    The set lacks creation tools for VMs and containers, which is a notable gap for a complete lifecycle surface. Basic operations are covered, but creation is missing.

    Related MCP Connectors

    Related MCP Servers