SkillFoxx

Proxmox MCP Server

A Proxmox VE MCP server with 341 tools: virtual machines, containers, storage, cluster and backups, with a read-only mode.

  • 81 ★ on the repository
  • Last commit
  • MIT
MCP server

Broad access

Why this level

  • An agent can stop, delete and roll back virtual machines and run commands inside guests.
  • The Proxmox API token gives access to the whole cluster within the user's rights.
All reasons and checks

ry-ops/proxmox-mcp-serverAuthor:ry-ops

Install

Manual install

git clone https://github.com/ry-ops/proxmox-mcp-server && cd proxmox-mcp-server

Then `./setup.sh` or `uv sync`, the `PROXMOX_*` variables and a check with `./test-connection.sh`.

Access and checks

How we review

Broad accessThe tool can change data, run commands or handle secrets.

  • An agent can stop, delete and roll back virtual machines and run commands inside guests.
  • The Proxmox API token gives access to the whole cluster within the user's rights.

This is third-party code. Review the repository files before installing.

What it does

Proxmox MCP Server exposes the whole Proxmox VE API to an agent: 341 tools across 14 areas. Nodes, QEMU virtual machines and LXC containers, storage and backups, cluster and HA, access control, firewall, disks, Ceph, ACME, SDN, notifications and pools. Through the QEMU guest agent a command can run inside a VM with its exit code and output read back. Safety switches exist: `PROXMOX_READ_ONLY=true` leaves the client only 150 read tools, `PROXMOX_NO_DESTRUCTIVE=true` hides 73 tools that delete, stop or roll back, and `PROXMOX_PROTECTED_VMIDS` names VMs that no tool may change. Tools carry `readOnlyHint` and `destructiveHint` annotations, and `PROXMOX_AUDIT_LOG` writes one JSON line per write call. The set can be narrowed through `PROXMOX_TOOLSETS`: for example to 127 tools instead of 341.

Who it is for. Proxmox VE and homelab administrators who want to manage a cluster by talking to an agent without memorizing API calls.

Good fit when

  • You need a summary of VMs and storage usage across all nodes.
  • A VM snapshot is taken before an upgrade, then the change and a check from the built-in prompt recipe.
  • A template is cloned and the new machine starts at once while MCP waits for the task to finish.
  • `df -h` must run inside a guest with the output read through the guest agent.
  • A client gets read-only access for monitoring with the `PVEAuditor` role.

Not a fit when

  • The cluster is production while the token has full rights and no protected VMs: an agent error could delete a machine.
  • You only need `qm` and `pct` on one node with no API token.
  • The Proxmox VE version is below 6.0.

Example request

Show all virtual machines in my Proxmox cluster and storage usage on every node, change nothing.

MCP

Transport
stdio, http
Authentication
API key

Environment variables

PROXMOX_HOST required
Proxmox VE server address.
PROXMOX_USER required
Proxmox user, for example `root@pam`.
PROXMOX_TOKEN_NAME required
API token name.
PROXMOX_TOKEN_VALUE required, secret
API token value.
PROXMOX_READ_ONLY
When `true` the server refuses every write.

Limitations

Proxmox VE 6.0 or newer and Python 3.10 with `uv`, or Docker, are required. The API token is created in Datacenter, Permissions, API Tokens, and for full access Privilege Separation is turned off so the token inherits user rights. Set `PROXMOX_HOST`, `PROXMOX_USER`, `PROXMOX_TOKEN_NAME` and `PROXMOX_TOKEN_VALUE`. Without read-only mode the agent can stop, delete and roll back machines and run commands inside guests. For monitoring use a token with the `PVEAuditor` role and `PROXMOX_READ_ONLY=true`.

How to disable. Remove the `proxmox` entry from the MCP client config, stop the container if run in Docker and revoke the token in Datacenter, Permissions, API Tokens.

FAQ

How do I connect Proxmox MCP Server?

Clone the repository, run `./setup.sh` or `uv sync`, set the `PROXMOX_*` variables and add `uv --directory /absolute/path run proxmox-mcp-server` to the client config. There is also the `ghcr.io/ry-ops/proxmox-mcp-server:latest` image.

How do I make access read-only?

Set `PROXMOX_READ_ONLY=true`: the server refuses every write and the client sees only 150 read tools. Use the `PVEAuditor` role for the token.

How do I protect important virtual machines?

List them in `PROXMOX_PROTECTED_VMIDS` and no tool will change those VMs. In addition `PROXMOX_NO_DESTRUCTIVE=true` hides 73 tools that delete, stop or roll back.

How do I wait for slow operations?

Clone, migrate, backup and restore take `wait: true`, and `wait_for_task` follows any task to the end and shows the log on failure.

How do I shrink the tool list?

The `PROXMOX_TOOLSETS=nodes,qemu,lxc,storage` variable keeps 127 tools instead of 341 and cuts context cost by more than half.

Discussion

No questions or reviews yet.

MCP servers

MCP server for Proxmox VE: manage VMs, LXC, snapshots and backups from an agent with permission control and command approval

MCP serverBroad access649
Official

A self-hosted homelab hub with a built-in MCP server: the agent gets 32 tools limited by per-key API scopes

MCP serverBroad access126

MCP Slim Guard sits between an agent and your MCP servers: it validates calls against schemas and returns big results in parts.

MCP serverExtended access180

A WebSSH console for VPS with an MCP server: the agent works across several servers while ACL tokens limit tools and hosts.

MCP serverBroad access133

A self-hosted gateway that merges several MCP servers into one endpoint with auth and tool selection

MCP serverBroad access2.8K

README in short

The server starts over stdio or through `proxmox-mcp-server-http` with per-client tokens and `read`, `operator` and `admin` roles. It is built on MCP SDK 2 and supports older clients, and `agent-card.json` describes tools for agent-to-agent discovery.

README badge

Report a problem