# Proximo — the governed client for Proxmox

> Proximo — the governed client for Proxmox is an open-source MCP server for cloud and infrastructure. Operate Proxmox through an AI agent with planned changes, receipts and undo. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted, Linux, macOS, Windows
- **Repository:** https://github.com/john-broadway/proximo
- **MCP Registry name:** io.github.john-broadway/proximo-proxmox
- **Categories:** cloud and infrastructure, security
- **Listing updated:** 2026-11-15

## About

Proximo is a governed client for the Proxmox family: PVE, PBS, PMG and PDM. Its idea is that an agent should be able to run a hypervisor without being able to wreck it. Every mutation first returns a recorded plan showing the verdict, the live target, the exact change and its blast radius. Changes need a confirm, and each produces a keyed, hash-chained receipt that `audit_verify` can check for edits, reordering and insertion.

Undo is built in where the platform allows: before a change the current record is captured so it can be restored through the vendor's own write. A command run inside a container can take a snapshot first and refuses to run if it cannot. That in-container lane is opt-in, with a fail-closed allowlist.

It exposes only six tools covering every address the four products publish, rather than one per endpoint, so the surface fits a small local model's context. The README advises starting with a read-only API token, and a `doctor` command reports what a token can do. It says there is no cloud and no phone-home, and the project is a community effort.

## Features

- **Plan before change:** Each mutation returns a recorded preview with blast radius before anything runs.
- **Tamper-evident ledger:** HMAC-keyed, hash-chained receipts verified with audit_verify.
- **Undo from captured state:** The prior record is stored and restored via the vendor's own write.
- **Six tools:** One small surface spans PVE, PBS, PMG and PDM.
- **Guarded container commands:** Opt-in allowlist and snapshot-first behaviour.
- **Read-only by default:** Start with a read-only token; doctor checks token capabilities.

## Good for

- Diagnose why a container is thrashing
- Apply a change with a plan and receipt
- Roll back a modification from a receipt
- Audit what an agent changed on a hypervisor
- Cover Proxmox Backup and Mail Gateway from one client

## Install

### Claude Code (Terminal)

```sh
claude mcp add proximo-proxmox -- uvx proximo-proxmox
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "proximo-proxmox": {
      "command": "uvx",
      "args": [
        "proximo-proxmox"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "proximo-proxmox": {
      "command": "uvx",
      "args": [
        "proximo-proxmox"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "proximo-proxmox": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "proximo-proxmox"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "proximo-proxmox": {
      "command": "uvx",
      "args": [
        "proximo-proxmox"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "proximo-proxmox": {
      "command": "uvx",
      "args": [
        "proximo-proxmox"
      ]
    }
  }
}
```

## Tools

- `audit_verify`: Verify the audit ledger for edits, reordering and insertion.

## FAQ

### Can an agent change things without approval?

No mutation runs on the first call; it returns a plan, and one confirm call records and performs it.

### Does it phone home?

The README says there is no cloud, no phone-home and no standing server unless you opt in.

### How is the token supplied?

As a file path in PROXIMO_TOKEN_PATH, so the secret never lands in client config.

### How can I verify the artifact?

The README points to signed images, PyPI provenance, an SBOM and an OpenSSF Scorecard.

### Is Proximo — the governed client for Proxmox free?

Yes. Proximo — the governed client for Proxmox is open source, so you can use and self-host it for free.

### How do I add Proximo — the governed client for Proxmox to Claude Code?

Run this command in your terminal: claude mcp add proximo-proxmox -- uvx proximo-proxmox

### What are the best alternatives to Proximo — the governed client for Proxmox?

The closest alternatives to Proximo — the governed client for Proxmox are REA, Agent Roast, Midplane, Leash and Tinplate Edge AI Safety, Security & EU Compliance.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Agent Roast](https://ai-powered.com/mcp/agent-roast): Agent Roast is an open-source MCP server for developer tools.
- [Midplane](https://ai-powered.com/mcp/midplane): Midplane is an open-source MCP server for databases.
- [Leash](https://ai-powered.com/mcp/leash): Leash is a free MCP server for security.
- [Tinplate Edge AI Safety, Security & EU Compliance](https://ai-powered.com/mcp/tinplate-edge-ai-safety-security-and-eu-compliance): Tinplate Edge AI Safety, Security & EU Compliance is a freemium MCP server for security.
- [SecureCloud](https://ai-powered.com/mcp/securecloud): SecureCloud is a free MCP server for security.
- [Eikino](https://ai-powered.com/mcp/eikino): Eikino is a freemium MCP server for security.
- [SynomosAI Governance MCP](https://ai-powered.com/mcp/synomosai-governance-mcp-2): SynomosAI Governance MCP is an open-source MCP server for security.

---
Source: https://ai-powered.com/mcp/proximo-the-governed-client-for-proxmox
