Provides read-only visibility into a Proxmox VE cluster, including nodes, guests (LXC and QEMU), storage, snapshots, backups, and Docker workloads running inside guests.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@proxmox-mcp show me the current status of all nodes and guests"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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.
Related MCP server: proxmox-mcp
Python 3.11+
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.
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-mcpOr from a local clone:
git clone https://github.com/edymol/proxmox-mcp
cd proxmox-mcp
uv tool install --from . proxmoxmcpPin the interpreter if you want the declared minimum rather than whatever uv picks:
uv tool install --python 3.11 --from . proxmoxmcpFind 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.
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 itNothing 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 trueThe 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:
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.
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.
Tool | Returns |
| Every node: online state, cores, memory, root filesystem, uptime, PVE version |
| One node in detail: CPU, memory, swap, per-mount filesystems, headroom |
| Every LXC and VM, running and stopped, with node, resources, pool, tags |
| Cores, memory, disks, network interfaces with bridge and gateway, features |
| Live state, uptime, CPU, memory, disk and network counters, HA state |
| Storage entries with type, content, totals, and a per-node breakdown |
| Snapshots for one guest with parent, description, timestamp, RAM flag |
| Backup volumes with guest, format, size, timestamp, newest age per guest |
| Whether an address is in use, with the evidence for the answer |
| Docker containers in an LXC: image, state, health, ports, compose labels |
| One compose project: services, images, states, networks, mount paths |
| 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.
uv sync
uv run ruff checkThe 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.
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.
MIT. See LICENSE.
Whether one address inside the profile's configured networks is in use.
Read-only and idempotent. Combines every guest configuration in the cluster, the neighbour table of one node, and one probe, and reports the evidence for its conclusion.
Refuses any address outside permitted_networks, before any command is issued. Raises
ProfileError naming the setting when no network is configured; it never guesses a range.
Reports inconclusive rather than guessing. A partial answer may report in_use but
never free: absence of evidence is not evidence of absence, and a wrong free means a
duplicate address on a live network.
Inputs: ip (required), profile. Returns: Whether one address is in use. `address` is a query subject, not a connection t…
One guest's configuration, on exactly the node named.
Read-only and idempotent. Returns cores, memory, swap, disks and their storage, network interfaces with bridge, address, and gateway, the unprivileged flag, the OS template, boot-on-start, and features. It never returns a password, a cloud-init password, or an SSH public key: there is no field for one.
A vmid the cluster does not report on the node named raises a structured error naming both. A config that cannot be read yields a partial result with a warning.
Inputs: node (required), vmid (required), profile. Returns: One guest's configuration. There is no field for a `password`, a `cipassword`,…
One guest's live status, on exactly the node named.
Read-only and idempotent. Returns state, uptime, CPU, memory, swap, disk read and write, network in and out, and the high-availability state.
A stopped guest is an answer, not a failure: it returns this model with its state, a
warning saying the live figures are not meaningful, and partial set. A vmid the cluster
does not report on the node named raises a structured error naming both.
Inputs: node (required), vmid (required), profile. Returns: Live status for one guest. A stopped guest is a partial result, not an error.
CPU, memory, swap, and per-mount filesystem utilization for exactly one node.
Read-only and idempotent. The per-mount figures and the memory detail come from the node
itself, so a node that cannot be reached yields a partial result naming it rather than an
exception. allocation compares what the resident guests are configured to claim against
what the node has.
Inputs: node (required), profile. Returns: CPU, memory, swap, and per-mount filesystem utilization for exactly one node.
One consolidated read of a guest, on exactly the node named.
Read-only and idempotent. Combines live status, resource pressure against the guest's
configured limits, filesystem headroom, Docker container health counts, snapshot and
backup recency, and a short list of concrete concerns. Prefer this over calling
get_guest_status, list_snapshots, list_backups, and list_guest_containers
separately when the question is "how is this guest doing".
Each entry in concerns is a whole sentence naming both the observation and the
threshold it crossed, so it can be quoted to an operator without further interpretation.
An empty list means nothing that was read crossed a threshold; it does not mean everything
was read, which partial and warnings report.
Three states stay distinguishable and none of them is an error. A guest that is not
running reports its state, a warning, and no resource figures, because the zeroes the
cluster carries for it describe nothing. A guest without Docker reports
docker_available false and no container counts. A guest with no backup reports
backup_count 0 and a null age, never an age of zero.
A vmid the cluster does not report on the node named raises a structured error naming
both. Anything that could not be read yields a warning and partial, never an exception
that hides the rest of the answer.
Inputs: node (required), vmid (required), profile. Returns: One consolidated read of a guest: the first tool to reach for. `concerns` holds…
One compose project inside one LXC guest, on exactly the node named.
Read-only and idempotent. Reports the project's status, working directory, configuration file paths, and for each service its image, state, health verdict, working directory, published ports, attached networks, and persistent mounts, plus the networks the project owns.
Mount paths are returned; mount contents are never read -- no command form this server can issue opens a file. Environment variables are never returned, and neither are container labels or command lines.
An empty services list is an answer. A guest without Docker, a QEMU guest, and a guest
that simply does not run a project under that name all return one with partial false and
no warning: each is a question that was asked and definitively answered. A guest that is
not running and a listing that could not be read return one with partial true and a
warning, because those are questions that could not be asked. A single container whose
inspection fails still appears as a service, carrying what the container listing knew.
Inputs: node (required), vmid (required), project (required), profile. Returns: One compose project inside one guest.
Backup volumes with their guest, format, size, and timestamp, plus recency per guest.
Read-only and idempotent. Recency covers every guest in scope whether or not it has a backup, because a guest missing from a backup listing is the most important thing such a listing reports.
A storage that cannot be listed yields a warning and partial; the storages that could be
read are still reported.
Inputs: node, vmid, profile. Returns: source, backups, partial, profile, +3 more
Docker containers inside one LXC guest, on exactly the node named.
Read-only and idempotent. Reports each container's name, image, state, health verdict, creation time, published ports, compose project and service, and attached networks.
Environment variables are never returned, and neither are container labels or command lines: there is no field for any of them.
None of the four absences is an error. Docker not installed and a QEMU guest are both
complete answers with partial false and no warning, and they are told apart by
docker_available: false means the guest was asked and has no Docker, null means the
question does not apply because there is no pct exec path into a QEMU VM. A guest that is
not running and a listing that could not be read are questions that could not be asked:
docker_available false, partial true, and a warning saying which.
Inputs: node (required), vmid (required), profile. Returns: Docker containers inside one guest. `docker_available` has three states and the…
Every LXC and VM in the cluster, or a filtered subset.
Read-only and idempotent. Stopped guests are included: they are the ones a caller is most
likely to have forgotten about. A filter that matches nothing returns an empty list, not
an error. A guest the cluster reports as unknown -- which is what it says about a guest
on a node it cannot reach -- is still listed, with the result marked partial.
Inputs: node, status, profile, guest_type. Returns: Every guest, LXC and QEMU alike, stopped guests included, or a filtered subset.
Every node the cluster reports, with capacity, uptime, and PVE version.
Read-only and idempotent. A single-node installation is not a degenerate case: it reports one node and no cluster-wide quorum. An offline or unreadable node yields a partial result with a warning naming it, never an exception that hides the nodes that answered.
Inputs: profile. Returns: Every node the cluster reports, whatever its size. A single-node installation r…
Snapshots for exactly one guest, with parent, description, timestamp, and RAM state.
Read-only and idempotent. A guest that has never been snapshotted returns an empty list:
the endpoint always reports a current pseudo-entry, which is not a snapshot and is not
counted as one. Absence is an answer, not an error.
The node and vmid are bound together before anything is read, so this never answers about a guest on a node the caller did not name.
Inputs: node (required), vmid (required), profile. Returns: Snapshots for exactly one guest. No snapshots is an empty list, never an error.
Storage entries with their per-node status and a cluster-wide aggregate.
Read-only and idempotent. With node given, only that node's storage is reported and its
own pvesm status is what is read; without it, the first node in the profile that answers
supplies the free-space figures and every other node reports available_bytes as None.
A storage that cannot be read yields a warning and partial, never an exception that
hides the rest of the cluster.
Inputs: node, profile. Returns: source, partial, profile, storages, +2 more
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 12 tools
Every tool targets a distinct resource and action: configuration vs status, snapshots vs backups, guests vs containers, node listing vs capacity. The consolidated health summary explicitly positions itself as a higher-level read, not a duplicate. There is no real overlap or risk of misselection.
Eleven tools follow a consistent verb_noun snake_case pattern (list_*, get_*, check_*, inspect_*), with verbs semantically appropriate to each operation. The one exception is 'guest_health_summary', which is a noun phrase and breaks the pattern, but it is a single minor deviation.
Twelve tools is squarely in the well-scoped range (3-15) for a Proxmox introspection server. Each tool covers a meaningful read-only aspect of the cluster, and there is no redundancy or bloat. The count aligns with the apparent domain and purpose.
The surface covers the core read-only workflows: guest listing/status/config, node capacity, storage, snapshots, backups, container inspection, and IP availability. Minor gaps exist (e.g., no node network info, no task history), but these are not critical for the evident purpose of a monitoring/introspection MCP server.
Read-only MCP for AI usage profiles, leaderboards, stats, and docs; no writes or private data.
Read-only MCP server for AIStatusDashboard status, incidents, metrics, and fallback recommendations.
Read-only MCP server for RZ AI Labs — query its services, workshops, and contact info.
Read-only MCP server for interior design studios: projects, overviews, weekly activity. No writes.
