proxmox-mcp

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.

Status

Alpha. Built with API-token auth and explicit confirmation gates for mutating operations.

Run with Docker Compose

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 --build

By default the MCP server listens on:

http://127.0.0.1:8000/mcp

Default MCP transport settings in .env.example:

MCP_TRANSPORT=streamable-http
MCP_PORT=8000
MCP_PATH=/mcp

Inside 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.

Proxmox protocol configuration

Prefer HTTPS for the Proxmox API:

PVE_BASE_URL=https://proxmox.lan:8006
PVE_VERIFY_SSL=false # only for self-signed homelab certs

If you intentionally need plain HTTP for Proxmox, make it explicit:

PVE_BASE_URL=http://proxmox.lan:8006
PVE_ALLOW_INSECURE_HTTP=true

Plain HTTP sends credentials over the network. That is usually a bad idea outside a tightly controlled lab network.

Authentication

Prefer a Proxmox API token:

PVE_API_TOKEN_ID=user@pam!token-name
PVE_API_TOKEN_SECRET=replace-me

Password-ticket auth is also supported, but API tokens are cleaner for MCP:

PVE_USERNAME=user@pam
PVE_PASSWORD=replace-me

Hermes config for Docker HTTP MCP

mcp_servers:
  proxmox:
    url: "http://127.0.0.1:8000/mcp"
    timeout: 120
    connect_timeout: 30

If deployed on a remote host behind TLS:

mcp_servers:
  proxmox:
    url: "https://proxmox-mcp.example.internal/mcp"
    timeout: 120
    connect_timeout: 30

Run without Docker

Local stdio mode remains available for development:

MCP_TRANSPORT=stdio uvx proxmox-mcp
# or from a checkout:
MCP_TRANSPORT=stdio uv run proxmox-mcp

Local HTTP mode without Docker:

MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 MCP_PATH=/mcp uv run proxmox-mcp

Safety model

• GET 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.

Tool coverage

Phase 1: Read-only

• 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

Phase 2: Safe actions

• 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

Phase 3: Admin/provisioning + escape hatch

• pve_clone_vm

• pve_create_lxc

• pve_create_qemu_vm

• pve_delete_vm

• pve_resize_disk

• pve_set_vm_config

• pve_api_request

Development

uv sync --extra dev
uv run pytest
uv run ruff check .