Proxmox MCP Server: Setup and Safe API Tokens

Q: How do I add the Proxmox MCP server to Claude Code?

Put your Proxmox host and token in a config.json file, then run claude mcp add proxmox --env PROXMOX_MCP_CONFIG=/path/to/config.json -- uvx proxmox-mcp-plus. Run /mcp to check it is connected.

Q: What permissions does the Proxmox API token need?

As few as you can manage. Start with PVEAuditor on / to only read. Add PVEVMUser to start, stop and back up guests, and PVEVMAdmin on a resource pool to let it create and delete guests only in that pool. Use a token with privilege separation, and give the same roles to both the user and the token, because the token only gets what both have.

Q: Can the AI delete my VMs?

Yes, if the token allows it. delete_vm, delete_container and rollback_snapshot are tools the model can call. Stop that in Proxmox (no PVEVMAdmin role, or only on a test pool), and turn on high_risk_require_approval_token so deletes need a token you give it.

On this page

Proxmox MCP Server: Setup, Safe API Tokens and Our Grade (Nov 2026)

The most used Proxmox MCP server is ProxmoxMCP-Plus. Run it with uvx proxmox-mcp-plus and point it at your Proxmox host with an API token. It can create, stop and delete VMs, so give it its own token with the smallest role that works. TrustedMCP grades it B.

Which Proxmox MCP server?

Search "proxmox mcp" or "proxmox-mcp" and you will see a few projects. None of them is made by Proxmox.

ProxmoxMCP-Plus (RekklesNA/ProxmoxMCP-Plus): Python, MIT, about 640 GitHub stars, on PyPI as proxmox-mcp-plus and on GHCR as a Docker image. v0.6.9 shipped on 2026-11-04. This is the one we graded.
ProxmoxMCP (canvrno/ProxmoxMCP): the earlier, smaller server. Its last push was in February 2025.
Others, such as GethosTheWalrus/proxmox-mcp, are newer and smaller. We haven't graded them yet.

ProxmoxMCP-Plus covers what most homelabs need: VMs and LXC containers (create, start, stop, migrate, delete), snapshots and rollback, backups and restore, ISO and template downloads, storage and cluster status, and logs. Long Proxmox tasks come back with a job_id you can poll, retry or cancel.

Step 1: Make a Proxmox API token just for MCP

Don't hand the server your root@pam password or a full-power token. The server can do anything its token can, so the token is your real safety setting. On a Proxmox node shell, using the commands from the Proxmox user management docs:

# a separate user for the agent
pveum user add mcp@pve -comment "MCP agent"

# a token with privilege separation (the default), so it gets only the ACLs you give it
pveum user token add mcp@pve agent -privsep 1

# start read-only: PVEAuditor can see everything and change nothing
pveum acl modify / -user mcp@pve -role PVEAuditor
pveum acl modify / -token 'mcp@pve!agent' -role PVEAuditor

The token secret is shown once. Copy it now.

Why both lines? A privilege-separated token gets only what both the user and the token have. In Proxmox's words, "its effective permissions are calculated by intersecting user and token permissions." So when you raise a role later, raise it for the user and the token on the same path.

When you are ready to let the agent do more, add a bigger role on a smaller path instead of making the token stronger everywhere:

You want the agent to	Give the user and the token	On
Look around only	`PVEAuditor` ("read only access")	`/`
Start, stop and back up existing guests	`PVEVMUser`	`/vms`, or one resource pool
Create and delete guests	`PVEVMAdmin`	one resource pool such as `/pool/lab`

Proxmox describes PVEVMUser as able to view, back up, change CD-ROM settings, use the console and manage VM power, and PVEVMAdmin as able to fully administer VMs. If you create guests inside a pool with the pool option, ProxmoxMCP-Plus's tool reference says pool-scoped tokens also need Pool.Allocate on that pool.

Two more Proxmox features worth using:

Expiry: pveum user token add takes --expire <unix-time>, so a token you forget about stops working on its own.
Revoke: pveum user token remove mcp@pve agent kills the token without touching the user.

Check what the token can really do with pveum user token permissions mcp@pve agent.

Step 2: Install and connect ProxmoxMCP-Plus

It needs Python 3.11 or later. The README's recommended setup runs it with uvx. For Claude Desktop, Cursor and other JSON-config clients:

{
  "mcpServers": {
    "proxmox-mcp-plus": {
      "command": "uvx",
      "args": ["proxmox-mcp-plus"],
      "env": {
        "PROXMOX_HOST": "your-proxmox-host",
        "PROXMOX_USER": "mcp@pve",
        "PROXMOX_TOKEN_NAME": "agent",
        "PROXMOX_TOKEN_VALUE": "your-token-secret",
        "PROXMOX_PORT": "8006",
        "PROXMOX_VERIFY_SSL": "true"
      }
    }
  }
}

That is the README's snippet with the mcp@pve user from step 1 in place of its root@pam example. The README also offers a version that keeps the token out of your client config: set only PROXMOX_MCP_CONFIG to the path of a config.json file (copied from proxmox-config/config.example.json). We recommend that one, because client config files tend to end up in backups and dotfile repos. (More on this in where MCP API keys should live.)

Claude Code has no snippet in the README, but the same command works with claude mcp add:

claude mcp add proxmox --env PROXMOX_MCP_CONFIG=/path/to/config.json -- uvx proxmox-mcp-plus

Then run /mcp and ask for get_nodes to check it connects. Our Claude Code MCP setup guide explains the --env and -- parts.

The self-signed certificate catch

Homelab Proxmox hosts usually have a self-signed certificate, and ProxmoxMCP-Plus checks TLS by default. Setting verify_ssl to false is refused unless you also turn on dev mode. Don't. Instead, either make the machine that runs the server trust your Proxmox CA (Proxmox says to copy /etc/pve/pve-root-ca.pem from a node "out of band"), or give Proxmox a real certificate with its built-in ACME (Let's Encrypt) support. Both are in the Proxmox certificate docs.

Step 3: Lock down the risky tools

ProxmoxMCP-Plus has good guardrails, but most of them are off until you turn them on. In the config.json file:

Make deletes and rollbacks need your OK. A list of "high-risk" operations (delete_vm, delete_container, rollback_snapshot, restore_backup, migrate_vm, update_vm_config and more) is only logged by default (high_risk_mode: "audit_only"). To require an approval token that you hand the agent when you mean it, set "high_risk_require_approval_token": true and a long random "high_risk_approval_token" under command_policy.
Hide tools you don't use. mcp.tool_allowlist (or MCP_TOOL_ALLOWLIST) shows the model only the tools you list, for example ["get_nodes", "get_vms", "get_containers", "get_storage"]. A typo stops startup instead of quietly exposing more. See why fewer tools is safer and cheaper.
Leave command execution blocked. execute_vm_command (through the QEMU guest agent) runs commands inside a guest. The default command_policy mode is deny_all, which blocks every command that doesn't match an allow_patterns entry. The SSH-based container and node command tools don't even appear unless you add an ssh section.
Mark a host read-only. With the targets config you can list several Proxmox hosts and set "readonly": true on any of them. The server then refuses changes there even if the token could make them.

The Proxmox role is still the real limit. These settings sit on top of it, not in place of it.

Running it over HTTP

For a remote client, the Docker image serves MCP over Streamable HTTP on 127.0.0.1:8000 and won't start without an MCP_API_KEY (sent as a Bearer token), unless you opt out on purpose. There is an optional OAuth sign-in that stores its state in PostgreSQL. The server itself speaks plain HTTP, so if you reach it from another machine, put it behind an HTTPS reverse proxy or a private network such as Tailscale. Never expose port 8000, the OpenAPI bridge on 8811 or your Proxmox web UI to the open internet.

Is the Proxmox MCP server safe? Our grade

TrustedMCP grades the ProxmoxMCP-Plus listing B (see how we score servers):

Auth (lost points): one Proxmox API token per host, scoped only as far as you scope it in Proxmox. The README example uses root@pam, and high-risk actions are only logged by default. This is the biggest deduction.
Maintenance (full marks): v0.6.9 on 2026-11-04, with commits from six people in the last 60 days and dependency updates handled through Dependabot.
Known CVEs (full marks): no GitHub, PyPI or OSV advisories for the server. A CVE in its SSH library (paramiko, CVE-2026-44405) was dealt with by requiring paramiko 5.
Transport (lost points): stdio by default, and the Docker HTTP mode binds to localhost and needs a key, but it has no built-in TLS. Command execution is opt-in and blocked by default.

Why not lower? We found no advisories and real safety work: forced TLS checks, a deny-all command policy, opt-in SSH and a required key for HTTP. Why not an A? A stolen or over-powered token can wipe VMs, and the approval gate is off until you set it.

Our advice for a homelab: a dedicated mcp@pve token with privilege separation, PVEAuditor until you need more, a pool for anything the agent creates, approval tokens on, and snapshots before you let it change a guest. Keep tool approval on in your client too. For more, see MCP security best practices.

Running Proxmox at work and want an MCP server with your own approval rules and audit trail built in? Tell us about it.

Frequently asked questions

Is there an official Proxmox MCP server?

No. Proxmox doesn't publish one. ProxmoxMCP-Plus is a community project (MIT license) and the most used one, with about 640 GitHub stars. It talks to the normal Proxmox VE API with an API token.

How do I add the Proxmox MCP server to Claude Code?

Put your Proxmox host and token in a config.json file, then run claude mcp add proxmox --env PROXMOX_MCP_CONFIG=/path/to/config.json -- uvx proxmox-mcp-plus. Run /mcp to check it is connected.

What permissions does the Proxmox API token need?

As few as you can manage. Start with PVEAuditor on / to only read. Add PVEVMUser to start, stop and back up guests, and PVEVMAdmin on a resource pool to let it create and delete guests only in that pool. Use a token with privilege separation, and give the same roles to both the user and the token, because the token only gets what both have.

Which Proxmox MCP server should I use?

ProxmoxMCP-Plus is the one we graded (B) and the most used, with about 640 GitHub stars and a release on 2026-11-04 (v0.6.9). canvrno/ProxmoxMCP is the earlier, smaller server and its last push was in February 2025. GethosTheWalrus/proxmox-mcp and others are newer and smaller, and we haven't graded them. See the ProxmoxMCP-Plus listing.

Is the Proxmox MCP server safe to use?

It is a B on our scale. We found no advisories and it has real guardrails (forced TLS checks, a deny-all command policy, a required key for HTTP mode), but high-risk actions like deletes are only logged until you turn on high_risk_require_approval_token. Use a dedicated, privilege-separated token as in step 1. More in MCP security best practices.

Why does it fail with a TLS or certificate error?

ProxmoxMCP-Plus checks the Proxmox certificate and won't let you turn that off outside dev mode. Trust your Proxmox CA (/etc/pve/pve-root-ca.pem) on the machine running the server, or give Proxmox a Let's Encrypt certificate with its ACME support. Also check the hostname in your config matches the certificate.

Can the AI delete my VMs?

Yes, if the token allows it. delete_vm, delete_container and rollback_snapshot are tools the model can call. Stop that in Proxmox (no PVEVMAdmin role, or only on a test pool), and turn on high_risk_require_approval_token so deletes need a token you give it.