# Proximo — the Proxmox MCP you can hand the keys

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.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 58
- Author: john-broadway
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/john-broadway/proximo
- Updated: 2026-10-22
- HTML: https://affpapa.org/en/nevibecode/mcp/proximo-the-proxmox-mcp-you-can-hand-the-keys

## What it 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.

## Requirements
- Needs: Python and uv (commands run via uvx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add proximo-proxmox -- uvx proximo-proxmox
```
uvx runs the command named after the package; if the README names another one, use uvx --from proximo-proxmox <command>

### Codex

**Platform CLI**
```bash
codex mcp add proximo-the-proxmox-mcp-you-can-hand-the-keys -- uvx proximo-proxmox
```
uvx runs the command named after the package; if the README names another one, use uvx --from proximo-proxmox <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add proximo-the-proxmox-mcp-you-can-hand-the-keys uvx proximo-proxmox
```
uvx runs the command named after the package; if the README names another one, use uvx --from proximo-proxmox <command>

## When to use it
- 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
- 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

## Similar
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [Oh My Posh Validator](https://affpapa.org/en/nevibecode/mcp/oh-my-posh-validator.md) — MCP server · ★ 23643
- [Keploy](https://affpapa.org/en/nevibecode/mcp/keploy.md) — MCP server · ★ 18727
- [Coder](https://affpapa.org/en/nevibecode/mcp/coder.md) — MCP server · ★ 17160
- [mcp](https://affpapa.org/en/nevibecode/mcp/kubeshark-mcp.md) — MCP server · ★ 12109

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md