proxmox-mcp: Instructions file for Claude Code

CLAUDE.md

Project Overview

proxmox-mcp is a deliberately minimal MCP server for Proxmox VE — built for personal use, no extra layers. stdio by default, Streamable HTTP behind one env var. Exposes 50 tools covering nodes, QEMU VMs, LXC containers, storage, cluster operations, snapshots, guest IP lookup, RRD metrics and server self-description.

Public listings

• GHCR image: ghcr.io/akmalovaa/proxmox-mcp:latest (multi-arch amd64 + arm64). Preferred install path.
• PyPI: https://pypi.org/project/proxmox-ve-mcp/ — distribution name is proxmox-ve-mcp (the proxmox-mcp slot was already taken). Run via uvx proxmox-ve-mcp. The Python module is still imported as proxmox_mcp — [tool.uv.build-backend] module-name in pyproject.toml reconciles the two names.
• Glama: https://glama.ai/mcp/servers/akmalovaa/proxmox-mcp — builds the Dockerfile from main branch on Deploy.
• MCP Registry: published as io.github.akmalovaa/proxmox-mcp (check with curl "https://registry.modelcontextprotocol.io/v0/servers?search=io.github.akmalovaa/proxmox-mcp"). server.json declares both the pypi and oci packages; publishing is manual — see "Release flow".

Tech Stack

• Python 3.14 with UV package manager
• MCP Python SDK 2.x (mcp.server.mcpserver.MCPServer) — MCP server framework
• Proxmoxer — Proxmox REST API client
• Pydantic Settings — configuration from environment variables

Project Structure

├── Dockerfile                          # Multi-stage: uv builds the venv (--extra sentry), runs as uid 10001, EXPOSE 8000
├── compose.yaml                        # Dev-only: builds local image with build: .
├── .dockerignore                       # Deny-all + allowlist; keeps docs/ out of the context
├── .env.example                        # Template for local dev env vars
├── glama.json                          # Glama maintainers file
├── server.json                         # MCP Registry manifest (pypi + oci packages)
├── .github/
│   ├── dependabot.yml                  # Monthly uv / actions / docker bumps
│   └── workflows/
│       ├── ci.yml                      # ruff + mypy + pytest + Docker build & stdio smoke test
│       └── docker-publish.yml          # Multi-arch GHCR publish on tag pushes 'X.Y.Z'
src/proxmox_mcp/
├── __init__.py
├── __main__.py                         # `uv run python -m proxmox_mcp`
├── server.py                           # MCPServer instance (+ instructions/icons/cache_hints), health routes, transport dispatch
├── config.py                           # Settings (PROXMOX_) + TransportConfig (PROXMOX_MCP_) + risk/allowlist/redaction readers
├── client.py                           # AppContext (lazy, lock-guarded ProxmoxAPI), process-wide singleton, lifespan
├── telemetry.py                        # setup_sentry() — optional, inert without SENTRY_DSN
└── tools/
    ├── __init__.py                     # register_all() — builds the Policy, registers all modules
    ├── _common.py                      # Policy, gate, error normalization, _ctx/_tier/_json/_redact/_compact, annotations
    ├── nodes.py                        # 10 tools: status, networks, disks, services, updates, rrd, tasks
    ├── vms.py                          # 17 tools: read + IPs/rrd + lifecycle/clone/migrate + snapshots
    ├── containers.py                   # 13 tools: read + IPs/rrd + lifecycle + snapshots
    ├── storage.py                      # 2 tools: list_storage, get_storage_content
    ├── cluster.py                      # 7 tools: status, resources, backups, ha, pools, log, next_vmid
    └── server_info.py                  # 1 tool: get_server_info (risk level, versions, tool counts)