The proxmox-mcp server exposes your Proxmox VE cluster to Claude Code, allowing you to monitor, manage, and provision virtual machines and LXC containers via the Proxmox REST API.
Cluster & Node Monitoring
List all nodes and their current status
Get detailed CPU usage, memory, and uptime for a specific node
List storage pools available on a node
VM & Container Inventory
List all VMs (QEMU) and containers (LXC) with their current status
Get detailed status and resource usage of a specific VM or container
List available CT templates and ISO images on a node's storage
Power Management
Start, stop, shutdown, or reboot any VM or container
Provisioning
Create a new LXC container from a template with configurable CPU, memory, disk, networking, hostname, SSH keys, and more
Create a new QEMU VM (empty or with an ISO attached) with configurable CPU, memory, disk, and network
Clone an existing VM or container template into a new instance
Notable Limitation: There is no destroy/delete tool — removing VMs or containers must be done directly in the Proxmox UI.
Allows interaction with a Proxmox VE cluster via its REST API, providing tools for managing VMs, containers, nodes, storage, and templates.
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 list all resources on the cluster"
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.
MCP server exposing your Proxmox VE cluster to Claude Code via the Proxmox REST API.
On the Proxmox host (or via the web UI):
# Create a dedicated user
pveum user add mcp@pve
# Create a role with the permissions needed for this server.
# Start with PVEVMAdmin (covers create/clone/start/stop for VMs and CTs)
# plus PVEAuditor (read-only access to nodes/storage).
pveum aclmod / -user mcp@pve -role PVEVMAdmin
pveum aclmod / -user mcp@pve -role PVEAuditor
# Create an API token for that user (copy the secret shown, it's only displayed once)
pveum user token add mcp@pve mcp-token --privsep 0This gives the token the same permission scope as the user. --privsep 0 means the
token inherits the user's full permissions (simpler). Set --privsep 1 and assign
ACLs to the token specifically if you want tighter scoping.
Note on "no delete" by design: the role above does not grant VM.Allocate
removal/destroy actions are still possible under PVEVMAdmin in some Proxmox
versions — if you want to be stricter, create a custom role excluding
VM.Config.* removal privileges. This server itself does not expose a destroy
tool, but a sufficiently broad token could still be used for destructive actions
via raw API calls if compromised. Keep the secret safe.
Related MCP server: Proxmox MCP Server
export PROXMOX_HOST="https://192.168.100.10:8006" # your Proxmox node, port 8006
export PROXMOX_TOKEN_ID="mcp@pve!mcp-token"
export PROXMOX_TOKEN_SECRET="<the-uuid-secret-from-step-1>"
export PROXMOX_TLS_INSECURE="true" # set if using the default self-signed certPut these in a .env file or your shell profile — do not commit them.
npm install
npm run buildAdd to your Claude Code MCP config (e.g. ~/.config/claude-code/mcp.json or via
claude mcp add):
{
"mcpServers": {
"proxmox": {
"command": "node",
"args": ["/absolute/path/to/mcp-proxmox/dist/index.js"],
"env": {
"PROXMOX_HOST": "https://192.168.100.10:8006",
"PROXMOX_TOKEN_ID": "mcp@pve!mcp-token",
"PROXMOX_TOKEN_SECRET": "your-secret-here",
"PROXMOX_TLS_INSECURE": "true"
}
}
}
}Run this on a machine with network access to your Proxmox API (VLAN 100 or
wherever 192.168.100.x is reachable — e.g. your workstation on VLAN 10, or
an LXC you SSH into).
Tool | Description |
| List cluster nodes and status |
| CPU/memory/uptime for a node |
| Storage pools on a node |
| All VMs and CTs on a node with status |
| Available CT templates / ISOs |
| Status of a specific VM/CT |
| start / stop / shutdown / reboot a VM/CT |
| Create a new LXC container from a template |
| Create a new empty QEMU VM (optionally with ISO) |
| Clone a VM/CT template |
There is intentionally no destroy/delete tool. Removing VMs/CTs should be done directly in the Proxmox UI.
VMIDs must be unique cluster-wide — check list_resources before creating.
net0 strings follow Proxmox syntax, e.g.
name=eth0,bridge=vmbr0,ip=192.168.100.50/24,gw=192.168.100.1 for static IP
on VLAN 100, or ip=dhcp for DHCP.
For LXC templates, download them first via pveam available / pveam download
on the node, or via the Proxmox UI (Storage → CT Templates).
Clone an existing VM or container template to create a new one. Requires confirming the configuration with the user before calling.
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | Proxmox node name | |
| type | Yes | Resource type of the source template | |
| templateVmid | Yes | VMID of the template to clone | |
| newVmid | Yes | New VMID for the clone | |
| name | Yes | Name/hostname for the clone | |
| storage | No | ||
| full | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It mentions a required confirmation step but fails to disclose other important behaviors such as whether cloning is destructive, whether the source is modified, or what the output (new resource) entails. The description is insufficient for a high-stakes mutation tool.
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?
Two concise sentences: the first states the core purpose, and the second adds a critical usage constraint. No redundant words, front-loaded, and easy to parse.
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 7 parameters (5 required), no output schema, and no annotations, the description is too brief. It does not explain the cloning process, expected results, error conditions, or the significance of key parameters like 'full'. The description leaves the agent underinformed for safe and effective 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?
Schema description coverage is 71% (moderate), and the description adds no additional information about parameters. It does not explain the role of templateVmid, newVmid, or the full/linked clone distinction. The description should compensate for gaps in the schema but does not.
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 action 'clone' and the resource 'an existing VM or container template', which distinguishes it from sibling tools like create_lxc and create_vm that create from scratch. The resource type is specific and 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 no guidance on when to use this tool versus alternatives. It mentions a requirement to confirm with the user, but does not specify contexts where cloning is appropriate or situations where other tools (e.g., create_vm) are better suited.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new LXC container from a template. Requires confirming the configuration with the user before calling.
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | Proxmox node name | |
| vmid | Yes | New CT ID (must be unused) | |
| ostemplate | Yes | Volume ID of the template, e.g. 'local:vztmpl/debian-12-standard_12.7-1_amd64.tar.zst' | |
| hostname | Yes | Hostname for the container | |
| storage | Yes | Storage ID for the rootfs, e.g. 'local-lvm' | |
| rootfsSizeGb | No | ||
| memoryMb | No | ||
| cores | No | ||
| password | No | ||
| sshPublicKey | No | ||
| net0 | No | name=eth0,bridge=vmbr0,ip=dhcp | |
| unprivileged | No | ||
| start | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description partially discloses behavior by mentioning the confirmation requirement. It does not address whether the operation is destructive, idempotent, or what permissions are needed, leaving gaps for safe agent execution.
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 with two sentences, front-loading the purpose. No wasted 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?
For a 13-parameter, 5-required tool with no output schema and no annotations, the description is insufficient. It omits return values, error handling, success criteria, and relationships to other tools like list_templates for finding templates.
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 only 38%, and the description adds no additional meaning to any parameter beyond the schema. The only hint is 'template' which loosely relates to ostemplate, but explicit parameter guidance is absent.
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 action ('Create a new LXC container') and the resource type ('from a template'), distinguishing it from sibling tools like create_vm which is for virtual machines.
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?
It provides one usage guideline: requiring user confirmation before calling. However, it does not explain when to use this tool over alternatives like clone_resource or create_vm, nor does it specify prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new QEMU VM (empty, optionally with an ISO attached for OS installation). Requires confirming the configuration with the user before calling.
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | Proxmox node name | |
| vmid | Yes | New VM ID (must be unused) | |
| name | Yes | VM name | |
| memoryMb | No | ||
| cores | No | ||
| storage | Yes | Storage ID for the disk, e.g. 'local-lvm' | |
| diskSizeGb | No | ||
| iso | No | ||
| net0 | No | virtio,bridge=vmbr0 | |
| ostype | No | l26 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. While it notes the need for user confirmation, it does not describe whether the VM is started after creation, authorization requirements, error handling for duplicate vmid, or side effects like resource consumption.
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 (two sentences) and front-loads the primary purpose. It avoids fluff but could be structured to separate purpose from usage note more clearly. Still, it is efficient and 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?
Given the complexity (10 parameters, 4 required, no output schema, no annotations), the description is incomplete. It omits return values, post-creation behavior, prerequisites (e.g., node/storage existence), and error handling, leaving significant gaps 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?
Of the 10 parameters, only 4 have schema descriptions (40% coverage). The tool description adds context for the 'iso' parameter (optional attachment) but does not explain the others (memoryMb, cores, diskSizeGb, net0, ostype), which lack documentation in both schema and description.
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 action ('Create a new QEMU VM') and resource ('empty, optionally with an ISO attached'), which distinguishes it from sibling tools like create_lxc (LXC containers) and clone_resource (cloning). It is specific and uses a strong verb-resource pairing.
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 mentions a workflow requirement ('Requires confirming the configuration with the user before calling'), which provides some usage guidance. However, it lacks explicit alternatives or when-not-to-use scenarios, such as preferring clone_resource over this for duplicating existing VMs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed status (CPU, memory, uptime) for a specific node.
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | Proxmox node name, e.g. 'behelit-services' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It correctly indicates a read operation but does not disclose potential error behaviors (e.g., node not found), rate limits, or side effects. For a simple status tool, it is somewhat adequate but lacks depth.
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 a single, clear sentence with no unnecessary words. It is front-loaded with the key information and does not waste any space.
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 only one parameter, no output schema, and no annotations, the description covers the core functionality adequately. However, it does not describe the response structure or error scenarios, which would be useful for 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 parameter 'node' has 100% schema description coverage, including an example value. The description does not add significant meaning beyond the schema; it merely restates that the tool returns status for a specific node. The schema already conveys the parameter's purpose.
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 uses a specific verb ('Get') and resource ('detailed status for a specific node'), listing specific fields (CPU, memory, uptime). It clearly distinguishes from siblings like 'get_resource_status' (which likely covers other resource types) and 'list_nodes' (which only lists nodes without detailed 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 description implies usage when detailed node status is needed, but does not explicitly state when to use this tool versus alternatives like 'get_resource_status' or 'list_nodes'. No exclusion criteria or prerequisite information is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get current status (running/stopped, resource usage) of a specific VM or container.
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | Proxmox node name | |
| type | Yes | Resource type | |
| vmid | Yes | VM/CT ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry full burden. It states it returns running/stopped and resource usage, but lacks details about permissions, error handling, rate limits, or behavior when resource doesn't exist.
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 a single sentence that is front-loaded with the core purpose and concise with 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?
Given no output schema, the description should explain what the output contains. It vaguely mentions 'running/stopped, resource usage' but lacks detail on format or structure. For a status tool, it is incomplete.
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 100%, and the description does not add meaning beyond the schema. It only repeats the tool's purpose; no parameter-specific details are given beyond what's in the schema.
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 the status of a specific VM or container, specifying the verb (Get) and resource (status). It distinguishes from sibling tools like get_node_status (node-level) and list_resources (list, not specific).
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 checking status but provides no explicit guidance on when to use this tool versus alternatives like list_resources (listing all) or get_node_status (node health). No exclusions or context are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all nodes in the Proxmox cluster with their status.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the tool lists nodes with status, but does not disclose authorization requirements, rate limits, idempotency, or potential errors. While the tool appears to be a simple read-only operation, the lack of behavioral context leaves the agent uncertain about safety and expected behavior.
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 a single, concise sentence with no redundant words. It front-loads the essential information and avoids elaboration, making it efficient for an AI agent to parse.
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 zero parameters, no output schema, and no annotations, the description is minimal. While it conveys the core purpose, it omits details such as the format of the returned status (e.g., online/offline, resource usage) or whether the tool requires authentication. For a simple tool, it is adequate but could be more informative.
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 has zero parameters, so schema description coverage is 100%. The description adds no parameter details because none exist, which is appropriate. Since there are no parameters, a baseline score of 4 is warranted.
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 action ('List'), the resource ('all nodes in the Proxmox cluster'), and the scope ('with their status'). It distinguishes from sibling tools like 'get_node_status' (which likely targets a single node) and 'list_resources' (which lists different resource types). The verb+resource combination is specific and 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?
No usage guidelines are provided. The description does not indicate when to use this tool versus alternatives like 'get_node_status' for detailed node info or 'list_resources' for a broader view. There is no mention of prerequisites, limitations, or recommended contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all VMs (qemu) and containers (lxc) on a node with their current status.
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | Proxmox node name, e.g. 'behelit-services' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It does not state that this is a read-only operation, nor does it disclose any side effects, authorization needs, or output format details. The term 'list' implies non-destructive behavior, but more explicit transparency would be beneficial.
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 a single, well-structured sentence that is front-loaded with the action. Every word adds value, and there is no extraneous information. It is highly concise and efficient.
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 simplicity of the tool (one required parameter, no output schema), the description is mostly complete. It clearly states the scope and result. Minor potential additions like mentioning the output format (e.g., 'Returns a list of resources with status') would slightly improve completeness, but it is already sufficient.
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 100% description coverage for the single parameter 'node', with a clear example. The description adds context by tying the parameter to the action of listing resources. This meets the baseline for a simple parameter, with no additional enrichment needed.
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 specifies the verb 'List', the resource types 'VMs (qemu) and containers (lxc)', and the scope 'on a node with their current status'. It effectively distinguishes this tool from siblings like list_nodes or get_resource_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 description implies usage for listing all resources on a given node, but it does not explicitly guide when to use alternatives like get_resource_status for a single resource or get_node_status for node-level status. No boundary conditions or prerequisites are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List storage pools available on a node.
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | Proxmox node name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility. It only states the tool lists storage pools, without disclosing whether it is read-only, requires authorization, or any side effects. Simple tools still benefit from mentioning safe behavior.
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?
Single sentence with no redundant information. Efficiently states purpose.
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?
No output schema exists, and the description does not mention return format or example. For a list operation, it lacks completeness about what the agent can expect.
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 coverage is 100% with a description for the node parameter. The description reinforces that the node is the context for listing, but adds no new parameter details beyond the schema.
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 specifies a clear action ('List storage pools') with a scope ('available on a node'). It is distinct from sibling tools like list_nodes or list_resources.
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?
No guidance on when to use this tool over alternatives. The description does not mention prerequisites or usage context, leaving the agent to infer based on the single required parameter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List available CT templates and ISO images on a node's storage.
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | Proxmox node name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
In the absence of annotations, the description implies a non-destructive read operation but does not elaborate on ordering, filtering, or limitations. Adequate but minimal.
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?
Single sentence, no fluff, front-loaded. Every word 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?
For a simple list tool with one parameter and no output schema, the description is nearly complete. Minor gap: no mention of return format (e.g., array) or potential errors.
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 coverage is 100%, and the description references the parameter context (node's storage). However, it adds no new meaning beyond the schema's own description.
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 action (list), the resources (CT templates and ISO images), and the scope (on a node's storage). It distinguishes from sibling tools like list_nodes or list_storage.
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?
No guidance on when to use this tool versus alternatives (e.g., list_storage, list_resources). No mention of prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start, stop, shutdown, or reboot a VM or container.
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | Proxmox node name | |
| type | Yes | Resource type | |
| vmid | Yes | VM/CT ID | |
| action | Yes | Power action |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only states the actions, omitting details about side effects, permissions required, or error conditions. This is insufficient for a mutating operation.
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 a single sentence with no fluff, but it is too brief for a tool with 4 required parameters. It lacks structure such as bullet points or examples, making it minimally helpful.
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 (4 required params, no output schema, no annotations), the description is incomplete. It does not explain return behavior, error scenarios, or prerequisites like the VM/CT needing to exist.
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 100%, so the schema already documents all 4 parameters. The description adds no additional meaning beyond listing the possible actions, which are already in the schema's enum.
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's purpose: to start, stop, shutdown, or reboot a VM or container. It uses specific verbs and identifies the resource type, distinguishing it from sibling tools like create_vm or list_resources.
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?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, when-not-to-use, or relationships with other tools like get_resource_status.
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.0clone_resourcecreate_lxccreate_vmget_node_statusget_resource_statuslist_nodeslist_resourceslist_storagelist_templatespower_actionScored across 10 tools
Each tool has a clear, distinct purpose: creation, cloning, status queries, listing, and power actions. No two tools overlap in functionality, minimizing confusion for an agent.
All tools follow a consistent snake_case verb_noun pattern (e.g., create_vm, list_nodes), making the naming predictable and easy to navigate.
With 10 tools, the server is well-scoped for Proxmox management, covering essential operations without unnecessary bloat or deficit.
Core CRUD-like operations are present: create, read (list/status), update (power action), but delete functionality is missing. This minor gap prevents full lifecycle management.
Provides capabilities that let LLM agents perform a range of infrastructure management tasks.
Create projects, nodes, and tasks in UluP Spaces by conversation with Claude.
Manage Rackspace Spot Kubernetes Cloudspaces, node pools, and VMs from your AI assistant.
Use AI models for chat, image, and video generation from Claude Code and other MCP hosts.
