mcp-proxmox

Read-only MCP server for the Proxmox VE API.

Scope is intentional and finished: GET-only tools, secret redaction, least-privilege token. There is no roadmap to add write/mutate operations. If you need an agent that starts VMs, edits config, or runs backups, use a different project (see Alternatives).

Designed for local MCP clients against a Proxmox cluster reached over a private network (VPN / reverse proxy recommended).

When to use this

• You want structured, current Proxmox state in an MCP client (Cursor, Claude Desktop, Codex, …).
• You want a hard read-only boundary (HTTP client cannot issue non-GET; no write tools registered).
• You accept a small fixed tool catalog instead of raw API exploration.

When not to: if your agent already has a shell and you can call the Proxmox API with env-backed wrappers / curl, that is often simpler and more flexible than maintaining an MCP server. Prefer that when the goal is personal automation, not a shared MCP tool surface.

Features

• Token auth (PVEAPIToken=…)
• HTTP client that only issues GET
• Secret redaction (cipassword, sshkeys, …)
• Tools: nodes, guests (QEMU/LXC), storage, firewall, backups, recent tasks

Requirements

• Python 3.11+
• Poetry
• A Proxmox API token with PVEAuditor (or equivalent read-only role)
• Network path to the API (VPN + private reverse proxy recommended)

Setup

cp .env.example .env   # set PROXMOX_URL, PROXMOX_TOKEN_ID, PROXMOX_TOKEN_SECRET
poetry install

See SETUP.md for creating mcp@pve!readonly in the Proxmox UI.

Run (stdio)

poetry run mcp-proxmox

MCP client config

Point your client at the in-project Poetry venv (after poetry install with virtualenvs.in-project = true):

{
  "mcpServers": {
    "proxmox": {
      "command": "/absolute/path/to/mcp-proxmox/.venv/bin/python",
      "args": ["-m", "mcp_proxmox"],
      "envFile": "/absolute/path/to/mcp-proxmox/.env"
    }
  }
}

On Windows, use .venv\\Scripts\\python.exe instead of .venv/bin/python.

Works the same way for Cursor, Claude Desktop, Codex, or any stdio MCP client.

Inspector

npx @modelcontextprotocol/inspector poetry run mcp-proxmox

Connectivity check

poetry run mcp-proxmox-check
poetry run mcp-proxmox-check --check-write-denied   # optional ACL probe

Tests

poetry run pytest
poetry run ruff check .
poetry run ruff format --check .

Env vars

Security model

• The HTTP wrapper exposes only GET; non-GET methods are not available on the client.
• Responses are recursively redacted for known secret keys (password, sshkeys, token, …).
• Use a least-privilege token (PVEAuditor) with privilege separation enabled.
• Do not expose Proxmox :8006 on the WAN; reach it over VPN or a private reverse proxy.

Alternatives

• Shell + API (often better for personal use): env file + GET-only curl / small wrappers. More flexible path coverage; no MCP process to maintain. Secrets stay in the environment instead of a separate MCP config if you already work that way.
• Write / manage VMs: RekklesNA/ProxmoxMCP-Plus — MCP + OpenAPI oriented toward controlling VMs, LXCs, backups, and snapshots. Prefer that (or Terraform / Ansible / raw API) if you need mutate.

This repo stays read-only on purpose.

License

MIT