proxmox-mcp

A read-only Model Context Protocol server for Proxmox VE. It gives an AI assistant accurate, structured visibility into your cluster and the Docker workloads inside your guests — and it cannot change anything, by construction rather than by convention.

Works with any Proxmox cluster: single-node or multi-node, LXC or QEMU or both, any addressing scheme, any SSH username, any storage backend.

Why read-only is structural here

Several Proxmox MCP servers exist. Most expose stop_guest, delete_guest, or exec_command alongside their read tools. This one cannot, and the difference is not a promise in a README:

• No mutating tool is registered, and no code path for one exists.
• Every command is matched against an allowlist before a connection is opened. 18 permitted forms, exact-match on the whole argument vector. Anything else is refused and audited.
• There is no generic shell. No tool accepts an arbitrary command string. docker --format values are pinned literals, because a Go template is an expression language — --format '{{.Config.Env}}' would print your container secrets.
• Container environment variables are never returned. The docker inspect template projects only the fields the tools consume, so environment is never serialised on the far side at all.
• Your credentials never reach the model. A tool call passes at most a profile name. Hosts, users, and key paths are resolved server-side.
• Every call is audited, including refusals, with no argument value that could carry a secret.

The allowlist and its 18 refusal classes live in src/proxmoxmcp/transport/allowlist.py as declarative data, so they can be audited by reading rather than by tracing code. An independent adversarial pass — roughly 160 hostile inputs over stdio against the installed artifact: command separators, traversal, flag smuggling, unicode digits, poisoned configuration, concurrency, process kills — found no escape and no route to a mutating command.

Requirements

• Python 3.11+
• uv
• SSH access from the machine running the server to each Proxmox node, key-based and non-interactive. The server never manages keys and never prompts.

Install

uv is the supported path. Not yet on PyPI, so install from the repository.

A note on names, since they differ on purpose: the command you run is proxmox-mcp and the MCP server registers as proxmox-mcp. The Python distribution is proxmoxmcp, because proxmox-mcp, mcp-proxmox, proxmox-mcp-server and pve-mcp are all already taken on PyPI — by packages that install a top-level proxmox_mcp and therefore cannot coexist with each other. You only ever type proxmoxmcp when installing from a local path.

uv tool install git+https://github.com/edymol/proxmox-mcp

Or from a local clone:

git clone https://github.com/edymol/proxmox-mcp
cd proxmox-mcp
uv tool install --from . proxmoxmcp

Pin the interpreter if you want the declared minimum rather than whatever uv picks:

uv tool install --python 3.11 --from . proxmoxmcp

Find the installed executable — you need its absolute path to register it:

echo "$(uv tool dir --bin)/proxmox-mcp"

To try it without installing, uvx --from . proxmoxmcp runs it from a temporary environment.

Configure

Create ~/.config/proxmox-mcp/profiles.toml, or set $PROXMOX_MCP_HOME and put it there. An annotated example ships in the package at resources/profiles.example.toml.

[profiles.homelab]
nodes              = ["node-a", "node-b"]   # SSH destinations; one entry is fine
ssh_user           = "root"                 # optional, defers to your ssh_config
ssh_config         = "~/.ssh/config"        # optional, defers to the SSH default
permitted_networks = ["10.0.0.0/24"]        # optional, only check_ip_availability needs it

Nothing is guessed. Absent configuration produces an error naming the missing setting rather than a default. Verify SSH access first — BatchMode turns an unknown host key into a failure:

ssh -o BatchMode=yes node-a true

Register with an MCP client

The server speaks Model Context Protocol over stdio. Every MCP client provides its own configuration mechanism. Consult your client's documentation for the configuration file location and format.

Find the installed executable first:

echo "$(uv tool dir --bin)/proxmox-mcp"

Then register it by absolute path. The generic MCP stdio block below works with any client that accepts standard mcpServers configuration:

{
  "mcpServers": {
    "proxmox-mcp": {
      "type": "stdio",
      "command": "/absolute/path/to/proxmox-mcp",
      "args": [],
      "env": {}
    }
  }
}

For TOML-based configuration:

[mcp_servers.proxmox-mcp]
command = "/absolute/path/to/proxmox-mcp"
args = []

Two operationally important notes:

1. Configuration is read at process start. If you edit your client's configuration file, restart the client process. A refresh or reconnect inside a running session is not sufficient.

2. Some clients require per-tool approval. If your client is configured with a policy of never approving MCP tool calls automatically, you must explicitly approve each tool before it can be called. Without this configuration, every tool call is cancelled and reported as user cancellation, which reads like a server fault and is not one. Consult your client's documentation for the approval mechanism.

The twelve tools

Tool	Returns
list_nodes	Every node: online state, cores, memory, root filesystem, uptime, PVE version
get_node_capacity	One node in detail: CPU, memory, swap, per-mount filesystems, headroom
list_guests	Every LXC and VM, running and stopped, with node, resources, pool, tags
get_guest_config	Cores, memory, disks, network interfaces with bridge and gateway, features
get_guest_status	Live state, uptime, CPU, memory, disk and network counters, HA state
list_storage	Storage entries with type, content, totals, and a per-node breakdown
list_snapshots	Snapshots for one guest with parent, description, timestamp, RAM flag
list_backups	Backup volumes with guest, format, size, timestamp, newest age per guest
check_ip_availability	Whether an address is in use, with the evidence for the answer
list_guest_containers	Docker containers in an LXC: image, state, health, ports, compose labels
inspect_compose_stack	One compose project: services, images, states, networks, mount paths
guest_health_summary	One consolidated read with concrete concerns — start here

Ask "how is guest 101 doing" and a model should reach for guest_health_summary first.

Two behaviours worth knowing. check_ip_availability reports free only when every check ran and every check agreed — a partial answer may say in_use but never free, because a wrong free means a duplicate address on a live network. And list_storage reports available as null where no source measures it, rather than deriving total - used, which overstates real free space.

Development

uv sync
uv run ruff check

The test suite is not published here. It is maintained privately: 1225 tests across unit (against a fake transport, no network), integration (recorded cluster fixtures), installed (a UV-installed artifact outside the checkout), and portability layers, plus opt-in read-only live tests.

Stating the obvious consequence rather than glossing it: you cannot verify the claims in the section above from this repository alone. You can read transport/allowlist.py, which is declarative data and is the whole enforcement surface, and you can read every tool in tools/ and confirm none of them performs I/O. Those two readings are what the tests check. If you want the suite before pointing this at a hypervisor, ask.

Status, and what is not finished

v1 is read-only. Mutating tools (start_guest, create_lxc, and so on) are designed but deliberately not built: they need dry-run plans, confirmation tokens, and pre-destruction checks that do not exist yet.

Known limits, recorded rather than hidden:

• list_snapshots and list_backups presence paths were developed against synthetic fixtures. The cluster this was built against has no snapshots and no backups, so first contact with real ones deserves a careful look.
• Discovery contacts each configured node in turn with a 10-second connect timeout, and profiles are capped at 256 nodes. A profile full of unreachable-but-routable hosts is therefore slow; a wall-clock deadline on discovery is the real fix and is not written yet.
• Known open items are tracked outside this repository, not because they are hidden but because the ledgers are part of a private build process. The material ones are listed above.

Licence

MIT. See LICENSE.