Provides tools for managing Proxmox VE clusters, including read-only inspection, VM/container lifecycle operations, snapshots, migration, provisioning, and a generic API escape hatch.
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 VMs on node pve1"
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 Docker-first Model Context Protocol (MCP) server for Proxmox VE.
It exposes safe, structured tools for read-only cluster inspection, VM/container lifecycle operations, snapshots, migration, provisioning helpers, and a guarded generic Proxmox API escape hatch.
Alpha. Built with API-token auth and explicit confirmation gates for mutating operations.
Related MCP server: Proxmox MCP Server
Docker Compose is the primary supported way to run this MCP server.
cp .env.example .env
# edit .env with your Proxmox URL and token
docker compose up -d --buildBy default the MCP server listens on:
http://127.0.0.1:8000/mcpDefault MCP transport settings in .env.example:
MCP_TRANSPORT=streamable-http
MCP_PORT=8000
MCP_PATH=/mcpInside Docker, the app binds to 0.0.0.0 in the container, but Compose publishes it only on host loopback by default:
ports:
- "127.0.0.1:8000:8000"Do not publish this unauthenticated MCP endpoint on all interfaces unless you put real network controls in front of it.
Supported MCP transports:
streamable-http — default for Docker and most remote deployments
sse — legacy HTTP/SSE MCP transport
stdio — local subprocess mode
For HTTPS exposure of the MCP endpoint, put this service behind a reverse proxy such as Caddy, Traefik, or nginx and terminate TLS there. Keep the container on plain HTTP internally unless you have a specific reason to do otherwise.
Prefer HTTPS for the Proxmox API:
PVE_BASE_URL=https://proxmox.lan:8006
PVE_VERIFY_SSL=false # only for self-signed homelab certsIf you intentionally need plain HTTP for Proxmox, make it explicit:
PVE_BASE_URL=http://proxmox.lan:8006
PVE_ALLOW_INSECURE_HTTP=truePlain HTTP sends credentials over the network. That is usually a bad idea outside a tightly controlled lab network.
Prefer a Proxmox API token:
PVE_API_TOKEN_ID=user@pam!token-name
PVE_API_TOKEN_SECRET=replace-mePassword-ticket auth is also supported, but API tokens are cleaner for MCP:
PVE_USERNAME=user@pam
PVE_PASSWORD=replace-memcp_servers:
proxmox:
url: "http://127.0.0.1:8000/mcp"
timeout: 120
connect_timeout: 30If deployed on a remote host behind TLS:
mcp_servers:
proxmox:
url: "https://proxmox-mcp.example.internal/mcp"
timeout: 120
connect_timeout: 30Local stdio mode remains available for development:
MCP_TRANSPORT=stdio uvx proxmox-mcp
# or from a checkout:
MCP_TRANSPORT=stdio uv run proxmox-mcpLocal HTTP mode without Docker:
MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 MCP_PATH=/mcp uv run proxmox-mcpGET requests are allowed by default.
POST, PUT, and DELETE require confirm=true.
High-level lifecycle/provisioning tools also require confirm=true.
Secrets are never intentionally returned.
Generic API paths reject full URLs, query strings, fragments, traversal, encoded traversal, and encoded slash tricks.
Path segments are validated and encoded before being sent to Proxmox.
pve_get_version
pve_get_cluster_status
pve_list_nodes
pve_list_resources
pve_list_vms
pve_get_vm_status
pve_get_vm_config
pve_list_storage
pve_list_backups
pve_get_task_status
pve_get_node_metrics
pve_start_vm
pve_shutdown_vm
pve_stop_vm
pve_reboot_vm
pve_suspend_vm
pve_resume_vm
pve_create_snapshot
pve_delete_snapshot
pve_rollback_snapshot
pve_migrate_vm
pve_clone_vm
pve_create_lxc
pve_create_qemu_vm
pve_delete_vm
pve_resize_disk
pve_set_vm_config
pve_api_request
uv sync --extra dev
uv run pytest
uv run ruff check .Call any Proxmox API path. GET is allowed; POST/PUT/DELETE require confirm=true.
Inputs: path (required), method (required), params, confirm. Returns: object
Clone a QEMU VM. Requires confirm=true.
Inputs: node (required), newid (required), source_vmid (required), full, +4 more. Returns: object
Create an LXC container. Requires confirm=true.
Inputs: node (required), vmid (required), storage (required), ostemplate (required), +8 more. Returns: object
Create a QEMU VM. Requires confirm=true.
Inputs: node (required), vmid (required), ide2, name, +7 more. Returns: object
Create a VM/container snapshot. Requires confirm=true.
Inputs: node (required), vmid (required), snapname (required), confirm, +3 more. Returns: object
Delete a VM/container snapshot. Requires confirm=true.
Inputs: node (required), vmid (required), snapname (required), confirm, +1 more. Returns: object
Delete a VM/container. Requires confirm=true.
Inputs: node (required), vmid (required), purge, confirm, +2 more. Returns: object
Return Proxmox cluster status.
Inputs: no named parameters. Returns: object
Get node status and metrics.
Inputs: node (required). Returns: object
Get task status by UPID.
Inputs: node (required), upid (required). Returns: object
Return Proxmox VE version information.
Inputs: no named parameters. Returns: object
Get config for a QEMU VM or LXC container.
Inputs: node (required), vmid (required), vm_type. Returns: object
Get current status for a QEMU VM or LXC container.
Inputs: node (required), vmid (required), vm_type. Returns: object
List backup content for a node storage.
Inputs: node (required), storage (required). Returns: object
List Proxmox nodes.
Inputs: no named parameters. Returns: object
List cluster resources, optionally filtered by type such as vm, storage, node.
Inputs: resource_type. Returns: object
List storage globally or for a node.
Inputs: node. Returns: object
List QEMU VMs and LXC containers from cluster resources.
Inputs: no named parameters. Returns: object
Migrate a VM/container to another node. Requires confirm=true.
Inputs: node (required), vmid (required), target (required), online, +4 more. Returns: object
Reboot a VM/container. Requires confirm=true.
Inputs: node (required), vmid (required), confirm, vm_type. Returns: object
Resize a QEMU VM disk. Requires confirm=true.
Inputs: disk (required), node (required), size (required), vmid (required), +1 more. Returns: object
Resume a VM/container. Requires confirm=true.
Inputs: node (required), vmid (required), confirm, vm_type. Returns: object
Rollback to a snapshot. Requires confirm=true.
Inputs: node (required), vmid (required), snapname (required), confirm, +1 more. Returns: object
Update VM/container config. Requires confirm=true.
Inputs: node (required), vmid (required), config (required), confirm, +1 more. Returns: object
Gracefully shut down a VM/container. Requires confirm=true.
Inputs: node (required), vmid (required), confirm, timeout, +2 more. Returns: object
Start a VM/container. Requires confirm=true.
Inputs: node (required), vmid (required), confirm, vm_type. Returns: object
Hard stop a VM/container. Requires confirm=true.
Inputs: node (required), vmid (required), confirm, vm_type. Returns: object
Suspend a VM/container. Requires confirm=true.
Inputs: node (required), vmid (required), confirm, vm_type. Returns: object
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 28 tools
Most tools target a distinct resource/action combination, and lifecycle verbs like start, shutdown, stop, and reboot are clear. The main ambiguity comes from the overlapping read-only listing tools (list_resources, list_vms, list_nodes, list_storage), though the descriptions help differentiate them. pve_api_request is a deliberate escape hatch rather than a source of confusion.
All tools follow a consistent pve_verb_noun snake_case pattern. Verbs are predictable: list/get for reads, create/delete/set for mutations, and explicit lifecycle verbs for VM/container actions. There are no mixed naming conventions or vague generic names.
28 tools exceeds the 25+ threshold and feels heavy for a single server. Several listing and config tools could be consolidated, and the generic pve_api_request already provides broad fallback coverage. The domain is broad but the surface is larger than necessary.
Core VM/container lifecycle, snapshot management, migration, cloning, creation, deletion, config updates, and disk resize are covered. Notable gaps like LXC clone/resize and advanced storage/network management are not directly exposed, but pve_api_request provides a workaround. The surface has no critical dead ends.
MCP server for Product Management
A MCP server built for developers enabling Git based project management with project and personal…
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
