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.
| Name | Required | Description | Default |
|---|---|---|---|
| ip | Yes | ||
| profile | No |
| Name | Required | Description |
|---|---|---|
| source | Yes | |
| status | Yes | |
| address | Yes | |
| partial | No | |
| profile | Yes | |
| evidence | No | |
| warnings | No | |
| collected_at | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does so exceptionally. It discloses that the tool combines multiple sources, provides evidence for conclusions, can report 'inconclusive', and never reports 'free' based on absence of evidence. This is far more transparent than typical tool descriptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded: the first sentence states the core purpose, followed by key behavioral and safety constraints. Every sentence adds essential information with no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so return values are already specified. The description nonetheless explains the semantics of its conclusion ('in_use', 'free', 'inconclusive') and error cases, making it complete for an IP availability check. Minor gaps like parameter format do not undermine overall contextual completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains that 'ip' must be inside the profile's configured networks and within permitted_networks, and that 'profile' determines the network configuration. However, it does not specify the IP address format (IPv4 vs IPv6) or the behavior when 'profile' is null, leaving ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it checks whether an address is in use within the profile's configured networks. The verb 'check' and resource 'IP availability' are explicit, and the tool is distinct from all sibling tools, which focus on guests, nodes, storage, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: read-only, idempotent, refuses addresses outside permitted_networks, and raises ProfileError when no network is configured. These constraints effectively tell when the tool will succeed or fail, but it does not explicitly name alternative tools or state when to prefer them.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | ||
| vmid | Yes | ||
| profile | No |
| Name | Required | Description |
|---|---|---|
| node | Yes | |
| vmid | Yes | |
| cores | No | |
| disks | No | |
| source | Yes | |
| os_type | No | |
| partial | No | |
| profile | Yes | |
| features | No | |
| networks | No | |
| warnings | No | |
| guest_type | Yes | |
| protection | No | |
| swap_bytes | No | |
| os_template | No | |
| architecture | No | |
| collected_at | Yes | |
| memory_bytes | No | |
| unprivileged | No | |
| start_on_boot | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite lacking annotations, the description discloses important behavioral traits: it is read-only and idempotent, explicitly states what fields are returned, clarifies that secrets are never included, and describes error handling for unknown vmid and unreadable configs. This significantly exceeds basic expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and information-dense, with three sentences each serving a purpose: defining scope, listing return fields and exclusions, and describing error behavior. No redundant wording or unnecessary details are present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description need not enumerate return fields, but it does anyway, adding value. It covers return content, exclusions, error conditions, and partial result behavior, making it fully sufficient for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It clarifies the roles of 'node' and 'vmid' through natural language, but the optional 'profile' parameter is not explained at all. This partial coverage merits a mid-range score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a single guest's configuration on a specified node. It distinguishes itself from sibling list tools by emphasizing 'one guest' and listing specific configuration fields returned, making the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this tool is for retrieving a detailed configuration of a single guest on a specific node, implying it is not for listing or status checks. However, it does not explicitly name alternatives like list_guests or state when not to use this tool, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | ||
| vmid | Yes | ||
| profile | No |
| Name | Required | Description |
|---|---|---|
| node | Yes | |
| vmid | Yes | |
| cores | No | |
| source | Yes | |
| status | Yes | |
| partial | No | |
| profile | Yes | |
| warnings | No | |
| guest_type | Yes | |
| collected_at | Yes | |
| uptime_seconds | No | |
| disk_read_bytes | No | |
| disk_used_bytes | No | |
| swap_used_bytes | No | |
| disk_total_bytes | No | |
| disk_write_bytes | No | |
| network_in_bytes | No | |
| swap_total_bytes | No | |
| cpu_used_fraction | No | |
| high_availability | No | |
| memory_used_bytes | No | |
| network_out_bytes | No | |
| memory_total_bytes | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries the full burden, and it excels: it declares read-only/idempotent behavior, enumerates returned metrics, and explains two edge cases (stopped guest and unknown vmid) with concrete responses. This is exemplary disclosure beyond typical descriptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four compact sentences, each adding distinct value: purpose, safety/return scope, and two edge cases. No filler or repetition; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is well-covered in terms of behavior and return semantics, and an output schema exists. However, the undocumented 'profile' parameter and lack of alternative-tool guidance leave minor gaps, making it strong but not perfect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides no property descriptions (0% coverage), so the description must compensate. It gives some meaning to 'node' and 'vmid' through context, but the optional 'profile' parameter is never mentioned, leaving its semantics entirely undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The phrase 'One guest's live status, on exactly the node named' clearly identifies the operation as retrieving live status for a single guest on a specific node. This distinguishes it from sibling tools like get_guest_config and guest_health_summary, and the tool name supplies the missing verb.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly name alternatives or state when to prefer this tool over siblings. It offers contextual signals like 'live status' and 'exactly the node named' that imply per-node monitoring use, but no exclusionary guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | ||
| profile | No |
| Name | Required | Description |
|---|---|---|
| cpu | No | |
| node | Yes | |
| swap | No | |
| memory | No | |
| source | Yes | |
| partial | No | |
| profile | Yes | |
| warnings | No | |
| allocation | No | |
| filesystems | No | |
| collected_at | Yes | |
| uptime_seconds | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full weight. It explicitly states 'Read-only and idempotent', a critical safety property. It also discloses a key edge-case behavior: an unreachable node yields a partial result 'naming it rather than an exception.' The explanation of 'allocation' adds semantic depth about how the data is computed. This goes well beyond a typical opaque description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each with a distinct role: purpose, error behavior, and allocation semantics. It is front-loaded with the core purpose in the first sentence. No redundant phrases or filler; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so return value details are not required in the description. The description covers purpose, read-only/idempotent behavior, partial-failure handling, and the 'allocation' comparison. However, it is missing any explanation of the 'profile' parameter, which is an optional input that could materially affect the query. This gap prevents a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. It indirectly clarifies 'node' by stating 'exactly one node,' but it never mentions 'profile' by name or purpose. The 'allocation' concept might relate to profile, but no explicit linkage is made, leaving the profile parameter completely unexplained. The description adds minimal value for parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific resource enumeration: 'CPU, memory, swap, and per-mount filesystem utilization for exactly one node.' The scope ('exactly one node') clearly distinguishes it from sibling tools like list_nodes, which would return all nodes. The verb (get) is implicit but the noun phrase is precise and self-explanatory.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for a single node ('exactly one node') and notes the 'allocation' comparison for capacity planning. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention exclusions or direct the agent to list_* tools for broader queries. The guidance is mostly implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | ||
| vmid | Yes | ||
| profile | No |
| Name | Required | Description |
|---|---|---|
| node | Yes | |
| swap | No | |
| vmid | Yes | |
| cores | No | |
| memory | No | |
| source | Yes | |
| status | Yes | |
| partial | No | |
| profile | Yes | |
| concerns | No | |
| warnings | No | |
| containers | No | |
| filesystem | No | |
| guest_type | Yes | |
| backup_count | No | |
| collected_at | Yes | |
| snapshot_count | No | |
| uptime_seconds | No | |
| docker_available | No | |
| newest_backup_at | No | |
| cpu_used_fraction | No | |
| newest_snapshot_at | No | |
| newest_backup_age_seconds | No | |
| newest_snapshot_age_seconds | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses read-only and idempotent nature, explains the meaning of an empty concerns list, differentiates three non-error states (guest not running, no Docker, no backup), describes partial results and warnings, and specifies error behavior for unknown vmid. This is thorough and goes beyond a simple action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence adds value: purpose, read-only assurance, what is combined, usage guidance, concerns semantics, edge cases, and error handling. It is front-loaded with the main purpose and structured logically, making it easy to process.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully covers purpose, usage, behavioral nuances, and edge cases, while the presence of an output schema means return value format doesn't need to be in prose. It answers likely agent questions about when to use, what to expect, and how failures are handled, making it complete for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description should compensate. It implicitly references 'node' and 'vmid' in context ('on exactly the node named', 'a vmid the cluster does not report...'), but does not explicitly define them or their formats. The 'profile' parameter is never mentioned, leaving its purpose entirely undocumented. This is a clear gap for a 3-parameter tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it is a consolidated read of a guest on a given node, combining multiple health dimensions. It explicitly distinguishes itself from sibling tools like get_guest_status, list_snapshots, list_backups, and list_guest_containers by saying 'Prefer this over calling... separately'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: '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"'. This directly names alternatives and provides a selection criterion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | ||
| vmid | Yes | ||
| profile | No | ||
| project | Yes |
| Name | Required | Description |
|---|---|---|
| node | Yes | |
| vmid | Yes | |
| source | Yes | |
| status | No | |
| partial | No | |
| profile | Yes | |
| project | Yes | |
| networks | No | |
| services | No | |
| warnings | No | |
| working_dir | No | |
| collected_at | Yes | |
| config_files | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and exceeds it. It explicitly states the tool is 'Read-only and idempotent,' guarantees mount contents are never read, and that environment variables, labels, and command lines are never returned. It also explains the precise semantics of partial results and warnings, providing deep behavioral transparency beyond any typical annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence adds value. It is front-loaded with the core purpose, followed by a structured breakdown of report contents and then a well-organized explanation of edge cases. The formatting with bold markers for critical guarantees makes it easy to scan. Nothing feels redundant or wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the presence of an output schema, the description sufficiently covers what is inspected, what is returned, and how to interpret unusual cases. The only notable omission is the 'profile' parameter, which is optional and not explained. Otherwise, the description provides complete contextual guidance for selecting and invoking the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description gives meaningful clues for three of four parameters: 'node' is named, 'LXC guest' maps to vmid, and 'project' is the compose project name. However, the optional 'profile' parameter is never mentioned, and with 0% schema description coverage, the agent receives no additional clarity on what profile does or when to set it. The description partially compensates but leaves a gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear, specific statement: 'One compose project inside one LXC guest, on exactly the node named.' and then enumerates exactly what it reports (status, working directory, config paths, per-service details). This distinguishes it from sibling tools like 'list_guest_containers' or 'get_guest_config' by its focus on a single compose stack and its read-only inspection behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description establishes the precise scope: 'one compose project inside one LXC guest, on exactly the node named.' It also explains nuanced edge cases (empty services list, partial results with warnings, guests without Docker) that clarify when the tool is applicable and how to interpret responses. However, it does not explicitly name alternative tools for other scenarios, so it stops short of full when-to-use vs. when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| node | No | ||
| vmid | No | ||
| profile | No |
| Name | Required | Description |
|---|---|---|
| source | Yes | |
| backups | No | |
| partial | No | |
| profile | Yes | |
| recency | No | |
| warnings | No | |
| collected_at | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully shoulders behavioral disclosure. It clearly states the operation is read-only and idempotent, explains the semantics of missing backups, and details partial failure behavior with warnings and partial results. This is rich, valuable context beyond a basic listing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each earning its place. The first sentence states the core output, the second adds critical interpretive context, and the third clarifies failure behavior. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers key behavioral aspects such as read-only/idempotent, partial failures, and the significance of missing backups. An output schema exists, so return values need not be detailed. Slight gap remains around parameter usage configuration, but overall it is contextually sufficient for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain node, vmid, or profile, nor how they affect scope. The phrase 'per guest' and 'every guest in scope' hints at filtering, but the parameters themselves are not named or described, leaving the agent with inadequate guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Backup volumes with their guest, format, size, and timestamp, plus recency per guest.' This clearly defines what the tool returns and distinguishes it from sibling tools like list_snapshots or list_guests.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool by focusing on backup listings and recency per guest, but it does not explicitly name alternatives or state when not to use it. The context is clear enough for an agent to infer its use for backup assessment, but explicit exclusions would be stronger.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | ||
| vmid | Yes | ||
| profile | No |
| Name | Required | Description |
|---|---|---|
| node | Yes | |
| vmid | Yes | |
| source | Yes | |
| partial | No | |
| profile | Yes | |
| warnings | No | |
| containers | No | |
| collected_at | Yes | |
| docker_available | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and exceeds expectations. It states 'Read-only and idempotent' and then provides a detailed, nuanced explanation of four absence scenarios, including how docker_available and partial differentiate them. This level of behavioral disclosure is exceptional and prevents misinterpretation of edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place. It is front-loaded with the core purpose, then lists output fields, then explicitly states exclusions, and finally explains edge cases in a structured, logical progression. The length is justified by the complexity of the behavior being described, and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the presence of an output schema (which handles return values), the description is remarkably complete. It covers the purpose, the output fields, what is deliberately omitted, and the full semantics of failure/absence cases. The only minor gap is the undefined 'profile' parameter, but overall context for agent decision-making is exceptional.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description implicitly defines 'node' (the node named) and 'vmid' (the LXC guest) through the opening sentence. However, it does not mention the 'profile' parameter at all, and with 0% schema description coverage, the description must compensate but fails to explain this optional parameter. This is a notable gap, though the two primary parameters are clear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's purpose: listing Docker containers inside a specific LXC guest on a named node. It uses a specific verb ('list') and resource ('Docker containers ... inside one LXC guest'), and the scope is precise ('exactly the node named'). This distinguishes it from sibling tools like list_guests, which list guests themselves, and inspect_compose_stack, which inspects compose stacks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context about when this tool is appropriate: when you need container-level details within a particular LXC guest on a specific node. It does not explicitly name alternatives or say 'use X instead', but it clarifies what the tool does not return (env vars, labels, command lines) and explains the meaning of docker_available and partial, helping an agent decide if this tool fits. However, it stops short of explicit when-to-use vs. alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| node | No | ||
| status | No | ||
| profile | No | ||
| guest_type | No |
| Name | Required | Description |
|---|---|---|
| guests | No | |
| source | Yes | |
| partial | No | |
| profile | Yes | |
| warnings | No | |
| collected_at | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavioral traits: read-only and idempotent, stopped guests included, empty results on no match, and handling of unknown guests with partial markers. This goes well beyond structured fields and gives the agent critical expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: the first sentence states the core purpose, and each subsequent sentence adds a distinct behavioral detail. No filler or repetition. It is concise yet comprehensive.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 4 optional parameters and an output schema, the description covers important edge cases (stopped, empty, unknown) and explicitly notes partial results. It is complete for a list operation and sufficiently rich despite the absence of annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions 'filtered subset' and the behavior of filters that match nothing, but does not explain each parameter's meaning (node, status, profile, guest_type) beyond what the schema already shows. The schema's enums help, but the description falls short of fully documenting parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists every LXC and VM in the cluster, with optional filtering. It distinguishes from siblings like list_guest_containers by explicitly naming both LXC and VM guest types. The verb 'list' and specific resource are immediately clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides useful context for when to use this tool, such as the inclusion of stopped guests and the read-only/idempotent nature. However, it does not explicitly mention alternatives or when not to use it, so it stops short of a full exclusionary guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| profile | No |
| Name | Required | Description |
|---|---|---|
| nodes | No | |
| source | Yes | |
| partial | No | |
| profile | Yes | |
| quorate | No | |
| warnings | No | |
| collected_at | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without any annotations, the description fully carries the behavioral burden and excels: it discloses idempotence, read-only safety, single-node edge case behavior, and partial failure handling with warnings rather than exceptions. This goes beyond what annotations typically provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary purpose. The second sentence adds valuable edge-case and error-handling details without any fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, the presence of an output schema, and no annotations, the description covers the essential contextual aspects: what it returns, read-only behavior, single-node handling, and partial failures. The only minor gap is the unmentioned profile parameter, but it is optional and does not undermine overall completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description never mentions the 'profile' parameter, and schema coverage is 0%, so no meaning is added beyond the parameter's existence in the schema. The description does not compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence clearly states the tool lists all cluster nodes with specific attributes (capacity, uptime, PVE version), using a specific verb and resource that distinguishes it from siblings like get_node_capacity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage as a general node listing but provides no explicit when-to-use or when-not-to-use guidance, nor does it mention alternative tools. The single-node and partial-result notes give context but not direct selection criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | ||
| vmid | Yes | ||
| profile | No |
| Name | Required | Description |
|---|---|---|
| node | Yes | |
| vmid | Yes | |
| source | Yes | |
| partial | No | |
| profile | Yes | |
| warnings | No | |
| snapshots | No | |
| collected_at | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses read-only and idempotent behavior, the empty-list edge case with the 'current' pseudo-entry, and the node/vmid binding safety property. Since no annotations are provided, this thorough behavioral context fully carries the transparency burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, each with a distinct purpose: defining the operation, describing the empty-list edge case, and explaining the safety binding. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers edge cases, idempotency, and safety properties. With an output schema present, return values need not be described. It is complete for a simple read-only listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
It adds meaning to node and vmid by explaining they are bound together, and 'exactly one guest' implies vmid identifies the guest. However, the profile parameter is not mentioned at all, and with 0% schema coverage, this partial compensation leaves a gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists snapshots for exactly one guest, with specific fields (parent, description, timestamp, RAM state). This distinguishes it from sibling tools like list_guests and get_guest_status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'exactly one guest' provides clear context for when to use the tool. However, it does not explicitly name alternative tools or describe when not to use it, so it stops short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| node | No | ||
| profile | No |
| Name | Required | Description |
|---|---|---|
| source | Yes | |
| partial | No | |
| profile | Yes | |
| storages | No | |
| warnings | No | |
| collected_at | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so excellently. It discloses read-only and idempotent behavior, the aggregation algorithm when `node` is omitted, and the partial-failure handling (warning + 'partial' instead of a full exception). This is rich behavioral detail beyond what annotations would typically provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each earning its place: purpose, parameter behavior, and failure semantics. It is front-loaded with the core purpose and avoids any redundant wording. Perfect balance of completeness and brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has two optional parameters and a nuanced aggregation behavior; the description covers these thoroughly, including edge cases like node fallback and per-storage partial failures. An output schema exists to document return values, so the absence of field-level detail in the description is appropriate. No critical information is missing for correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema offers no descriptions for `node` or `profile`, and schema coverage is 0%. The description significantly compensates by thoroughly explaining the `node` parameter's effect on output and data source, and it references 'profile' in the context of cluster-wide behavior. However, the `profile` parameter itself remains somewhat undefined, so it adds strong but not complete semantic coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence clearly identifies the resource ('storage entries') and the output scope ('per-node status and a cluster-wide aggregate'), which distinguishes it from sibling tools focused on guests, nodes, and backups. Though it lacks an explicit verb, the tool name 'list_storage' and the noun phrase make the listing purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context on when to use the `node` parameter (restrict to one node) versus omitting it (cluster-wide with a fallback), effectively guiding usage. It does not explicitly name alternative tools or when not to use this one, but the read-only and idempotent nature implies appropriate scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0check_ip_availabilityget_guest_configget_guest_statusget_node_capacityguest_health_summaryinspect_compose_stacklist_backupslist_guest_containerslist_guestslist_nodeslist_snapshotslist_storageScored 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 server for AIStatusDashboard status, incidents, metrics, and fallback recommendations.
Read-only MCP server for RZ AI Labs — query its services, workshops, and contact info.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
The Google GKE MCP server is a managed Model Context Protocol server that provides AI applications with tools to manage Google Kubernetes Engine (GKE) clusters and Kubernetes resources. It exposes a structured, discoverable interface that allows AI agents to interact with GKE and Kubernetes APIs, enabling them to inspect cluster configurations, retrieve Kubernetes resource YAMLs, monitor operations like cluster upgrades, diagnose issues, and optimize costs—all without needing to parse text output or use complex kubectl commands.
