Proxmox VE — Claude Code MCP server: nodes, VMs, snapshots
An MCP server that lets your agent see Proxmox VE nodes, virtual machines, containers, storage and snapshots. Read-only unless you raise the risk level.
claude mcp add --env PROXMOX_HOST=<PROXMOX_HOST> --env PROXMOX_PORT=<PROXMOX_PORT> --env PROXMOX_VERIFY_SSL=<PROXMOX_VERIFY_SSL> --env PROXMOX_TIMEOUT=<PROXMOX_TIMEOUT> --env PROXMOX_USER=<PROXMOX_USER> --transport stdio proxmox-ve -- uvx proxmox-ve-mcpWhat Proxmox VE does
Fifty tools cover nodes, QEMU guests, LXC containers, storage, the cluster and snapshots. The default level is read, which registers 32 tools and none of them change anything. Destructive calls sit behind PROXMOX_RISK_LEVEL: lifecycle brings in start, stop, reboot, clone, migrate and snapshot creation, while all adds snapshot deletion and rollback. Anything above the active level is never registered, so it does not show up in your client's tool list at all.
Configuration is environment variables only — no config file, no database, no saved state. You need PROXMOX_HOST plus either the PROXMOX_TOKEN_NAME / PROXMOX_TOKEN_VALUE pair or PROXMOX_PASSWORD. Set just one half of the token pair and the server refuses to start; it will not quietly fall back to the password. Transport is stdio or Streamable HTTP, one variable apart, and HTTP binds to loopback. The image ghcr.io/akmalovaa/proxmox-mcp:latest ships for amd64 and arm64.
Give the token real permissions or some calls come back as 403. PVEAuditor is enough for all 32 read tools; PVEVMAdmin on /vms unlocks guest lifecycle and snapshots. Migration also wants VM.Migrate on the destination node, and cloning wants Datastore.AllocateSpace on the destination storage. A dedicated user with its own token beats root@pam here, since the server answers to a model reading text it did not write.
What it helps with
- list cluster nodes and their current state from chat
- start or stop one specific virtual machine
- take a snapshot before a risky change
- check how much space is left on a datastore
- find a container by name and read its config
Example prompts for the agent
- List all Proxmox nodes and their load
- Stop the VM with ID 101
- Snapshot container
web-01before the upgrade
How to install Proxmox VE
Platform CLI
claude mcp add --env PROXMOX_HOST=<PROXMOX_HOST> --env PROXMOX_PORT=<PROXMOX_PORT> --env PROXMOX_VERIFY_SSL=<PROXMOX_VERIFY_SSL> --env PROXMOX_TIMEOUT=<PROXMOX_TIMEOUT> --env PROXMOX_USER=<PROXMOX_USER> --transport stdio proxmox-ve -- uvx proxmox-ve-mcpReplace <…> with your own values. 14 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from proxmox-ve-mcp <command>
Platform CLI
codex mcp add proxmox-ve --env PROXMOX_HOST=<PROXMOX_HOST> --env PROXMOX_PORT=<PROXMOX_PORT> --env PROXMOX_VERIFY_SSL=<PROXMOX_VERIFY_SSL> --env PROXMOX_TIMEOUT=<PROXMOX_TIMEOUT> --env PROXMOX_USER=<PROXMOX_USER> -- uvx proxmox-ve-mcpReplace <…> with your own values. 14 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from proxmox-ve-mcp <command>
Config file
{
"mcpServers": {
"proxmox-ve": {
"command": "uvx",
"args": [
"proxmox-ve-mcp"
],
"env": {
"PROXMOX_HOST": "<PROXMOX_HOST>",
"PROXMOX_PORT": "<PROXMOX_PORT>",
"PROXMOX_VERIFY_SSL": "<PROXMOX_VERIFY_SSL>",
"PROXMOX_TIMEOUT": "<PROXMOX_TIMEOUT>",
"PROXMOX_USER": "<PROXMOX_USER>"
}
}
}
}Replace <…> with your own values. 14 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from proxmox-ve-mcp <command>
Config file
{
"servers": {
"proxmox-ve": {
"type": "stdio",
"command": "uvx",
"args": [
"proxmox-ve-mcp"
],
"env": {
"PROXMOX_HOST": "<PROXMOX_HOST>",
"PROXMOX_PORT": "<PROXMOX_PORT>",
"PROXMOX_VERIFY_SSL": "<PROXMOX_VERIFY_SSL>",
"PROXMOX_TIMEOUT": "<PROXMOX_TIMEOUT>",
"PROXMOX_USER": "<PROXMOX_USER>"
}
}
}
}Replace <…> with your own values. 14 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from proxmox-ve-mcp <command>
Platform CLI
gemini mcp add -e PROXMOX_HOST=<PROXMOX_HOST> -e PROXMOX_PORT=<PROXMOX_PORT> -e PROXMOX_VERIFY_SSL=<PROXMOX_VERIFY_SSL> -e PROXMOX_TIMEOUT=<PROXMOX_TIMEOUT> -e PROXMOX_USER=<PROXMOX_USER> proxmox-ve uvx proxmox-ve-mcpReplace <…> with your own values. 14 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from proxmox-ve-mcp <command>
Step 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 VE
How do I install the Proxmox VE MCP server in Claude Code?
Run `claude mcp add proxmox-mcp -e PROXMOX_HOST=<PROXMOX_HOST> -e PROXMOX_TOKEN_VALUE=<PROXMOX_TOKEN_VALUE> -e PROXMOX_PASSWORD=<PROXMOX_PASSWORD> -e SENTRY_DSN=<SENTRY_DSN> -- uvx proxmox-ve-mcp`. A second form spells out the stdio transport along with port, SSL and timeout variables.
What does the Proxmox VE MCP server do?
It exposes Proxmox VE nodes, QEMU VMs, LXC containers, storage, cluster and snapshots to your agent. Only read operations are available until you change the risk level.
Which Proxmox permissions does the token need?
PVEAuditor covers reading. Guest lifecycle and snapshots need PVEVMAdmin on /vms, migration needs VM.Migrate on the target node, and cloning needs Datastore.AllocateSpace on the target storage.
