Proximo — the Proxmox MCP: Claude Code MCP Server
Control Proxmox VE, PBS, PMG, and PDM through AI agents safely. It reviews mutation blast radius first and captures pre-change state before touching your hypervisor.
claude mcp add proximo-proxmox -- uvx proximo-proxmoxWhat Proximo — the Proxmox MCP you can hand the keys does
Proximo connects coding agents to four Proxmox platforms: PVE, PBS, PMG, and PDM. Rather than exposing hundreds of separate endpoints, it exposes six core tools. This compact surface fits neatly into standard context windows, including smaller local models.
Safety sits at the core of the dispatch layer. The server starts in read-only mode. Any mutation request halts first to produce an execution plan detailing the target and blast radius. For risky commands inside containers, Proximo demands a snapshot beforehand. If a snapshot cannot be taken, the operation cancels immediately.
Every change generates a verifiable record containing before-and-after states, allowing rollbacks through native API calls. Without Python 3.12+, running the server via uvx fails. The tool requires no external cloud connections, keeping all cluster credentials on your local hardware.
What it helps with
- diagnose guest container failures through node metrics and logs
- inspect mutation blast radius before modifying hypervisor settings
- create container snapshots automatically before executing risky fixes
- restore cluster configurations using pre-change state receipts
Example prompts for the agent
- Investigate high load on container 105 and inspect its system logs
- Plan a configuration update for VM 200 and require a snapshot before applying
- Show the receipt for the last storage mutation and roll back the change
How to install Proximo — the Proxmox MCP you can hand the keys
Platform CLI
claude mcp add proximo-proxmox -- uvx proximo-proxmoxuvx runs the command named after the package; if the README names another one, use uvx --from proximo-proxmox <command>
Platform CLI
codex mcp add proximo-the-proxmox-mcp-you-can-hand-the-keys -- uvx proximo-proxmoxuvx runs the command named after the package; if the README names another one, use uvx --from proximo-proxmox <command>
Config file
{
"mcpServers": {
"proximo-the-proxmox-mcp-you-can-hand-the-keys": {
"command": "uvx",
"args": [
"proximo-proxmox"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from proximo-proxmox <command>
Config file
{
"servers": {
"proximo-the-proxmox-mcp-you-can-hand-the-keys": {
"type": "stdio",
"command": "uvx",
"args": [
"proximo-proxmox"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from proximo-proxmox <command>
Platform CLI
gemini mcp add proximo-the-proxmox-mcp-you-can-hand-the-keys uvx proximo-proxmoxuvx runs the command named after the package; if the README names another one, use uvx --from proximo-proxmox <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 Proximo — the Proxmox MCP you can hand the keys
How to install Proximo in Claude Code?
Run claude mcp add proximo-proxmox -- uvx proximo-proxmox in your terminal. You need Python 3.12 or newer installed alongside uvx.
How does Proximo protect hypervisors from accidental damage?
It operates in read-only mode by default and generates a preview of the blast radius before altering settings. It also enforces snapshots before risky commands and tracks initial state for rollbacks.
Which Proxmox environments work with Proximo?
It supports four products: Proxmox Virtual Environment (VE), Backup Server (PBS), Mail Gateway (PMG), and Datacenter Manager (PDM).
