Skip to main content
Glama
Sign In
deenesjakoruzh
proxmox-mcp

proxmox-mcp

by plgonzalezrx8
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

proxmox-mcp

MCP-сервер (Model Context Protocol) для Proxmox VE, ориентированный на работу в Docker.

Он предоставляет безопасные структурированные инструменты для проверки кластера в режиме только для чтения, операций с жизненным циклом ВМ/контейнеров, создания снимков, миграции, помощников по подготовке ресурсов и защищенный универсальный шлюз для API Proxmox.

Статус

Альфа-версия. Реализована аутентификация через API-токен и явные шлюзы подтверждения для операций, изменяющих состояние.

Related MCP server: Proxmox MCP Server

Запуск с помощью Docker Compose

Docker Compose — основной поддерживаемый способ запуска этого MCP-сервера.

cp .env.example .env
# edit .env with your Proxmox URL and token
docker compose up -d --build

По умолчанию MCP-сервер прослушивает:

http://127.0.0.1:8000/mcp

Настройки транспорта MCP по умолчанию в .env.example:

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

Внутри Docker приложение привязывается к 0.0.0.0 в контейнере, но Compose по умолчанию публикует его только на локальном интерфейсе хоста:

ports:
  - "127.0.0.1:8000:8000"

Не публикуйте эту неаутентифицированную конечную точку MCP на всех интерфейсах, если вы не настроили перед ней реальные сетевые средства контроля.

Поддерживаемые транспорты MCP:

  • streamable-http — по умолчанию для Docker и большинства удаленных развертываний

  • sse — устаревший транспорт HTTP/SSE MCP

  • stdio — режим локального подпроцесса

Для доступа к конечной точке MCP через HTTPS разместите этот сервис за обратным прокси-сервером, таким как Caddy, Traefik или nginx, и завершайте TLS там. Оставьте контейнер на обычном HTTP внутри, если у вас нет особых причин поступать иначе.

Настройка протокола Proxmox

Предпочитайте HTTPS для API Proxmox:

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

Если вам намеренно требуется обычный HTTP для Proxmox, укажите это явно:

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

Обычный HTTP передает учетные данные по сети. Обычно это плохая идея вне строго контролируемой лабораторной сети.

Аутентификация

Предпочитайте API-токен Proxmox:

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

Аутентификация через пароль/тикет также поддерживается, но API-токены чище для MCP:

PVE_USERNAME=user@pam
PVE_PASSWORD=replace-me

Конфигурация Hermes для Docker HTTP MCP

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

При развертывании на удаленном хосте за TLS:

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

Запуск без Docker

Локальный режим stdio остается доступным для разработки:

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

Локальный режим HTTP без Docker:

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

Модель безопасности

  • Запросы GET разрешены по умолчанию.

  • Для POST, PUT и DELETE требуется confirm=true.

  • Инструменты высокого уровня для управления жизненным циклом/подготовки ресурсов также требуют confirm=true.

  • Секреты никогда не возвращаются намеренно.

  • Универсальные пути API отклоняют полные URL, строки запросов, фрагменты, обход путей, кодированный обход и трюки с кодированным слэшем.

  • Сегменты пути проверяются и кодируются перед отправкой в Proxmox.

Охват инструментов

Фаза 1: Только чтение

  • 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

Фаза 2: Безопасные действия

  • 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

Фаза 3: Администрирование/подготовка ресурсов + шлюз

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

Available Tools

28 tools
pve_api_requestC

Call any Proxmox API path. GET is allowed; POST/PUT/DELETE require confirm=true.

Inputs: path (required), method (required), params, confirm. Returns: object

pve_clone_vmC

Clone a QEMU VM. Requires confirm=true.

Inputs: node (required), newid (required), source_vmid (required), full, +4 more. Returns: object

pve_create_lxcC

Create an LXC container. Requires confirm=true.

Inputs: node (required), vmid (required), storage (required), ostemplate (required), +8 more. Returns: object

pve_create_qemu_vmC

Create a QEMU VM. Requires confirm=true.

Inputs: node (required), vmid (required), ide2, name, +7 more. Returns: object

pve_create_snapshotB

Create a VM/container snapshot. Requires confirm=true.

Inputs: node (required), vmid (required), snapname (required), confirm, +3 more. Returns: object

pve_delete_snapshotA

Delete a VM/container snapshot. Requires confirm=true.

Inputs: node (required), vmid (required), snapname (required), confirm, +1 more. Returns: object

pve_delete_vmC

Delete a VM/container. Requires confirm=true.

Inputs: node (required), vmid (required), purge, confirm, +2 more. Returns: object

pve_get_cluster_statusA

Return Proxmox cluster status.

Inputs: no named parameters. Returns: object

pve_get_node_metricsC

Get node status and metrics.

Inputs: node (required). Returns: object

pve_get_task_statusC

Get task status by UPID.

Inputs: node (required), upid (required). Returns: object

pve_get_versionA

Return Proxmox VE version information.

Inputs: no named parameters. Returns: object

pve_get_vm_configA

Get config for a QEMU VM or LXC container.

Inputs: node (required), vmid (required), vm_type. Returns: object

pve_get_vm_statusB

Get current status for a QEMU VM or LXC container.

Inputs: node (required), vmid (required), vm_type. Returns: object

pve_list_backupsB

List backup content for a node storage.

Inputs: node (required), storage (required). Returns: object

pve_list_nodesA

List Proxmox nodes.

Inputs: no named parameters. Returns: object

pve_list_resourcesB

List cluster resources, optionally filtered by type such as vm, storage, node.

Inputs: resource_type. Returns: object

pve_list_storageA

List storage globally or for a node.

Inputs: node. Returns: object

pve_list_vmsA

List QEMU VMs and LXC containers from cluster resources.

Inputs: no named parameters. Returns: object

pve_migrate_vmB

Migrate a VM/container to another node. Requires confirm=true.

Inputs: node (required), vmid (required), target (required), online, +4 more. Returns: object

pve_reboot_vmA

Reboot a VM/container. Requires confirm=true.

Inputs: node (required), vmid (required), confirm, vm_type. Returns: object

pve_resize_diskC

Resize a QEMU VM disk. Requires confirm=true.

Inputs: disk (required), node (required), size (required), vmid (required), +1 more. Returns: object

pve_resume_vmB

Resume a VM/container. Requires confirm=true.

Inputs: node (required), vmid (required), confirm, vm_type. Returns: object

pve_rollback_snapshotC

Rollback to a snapshot. Requires confirm=true.

Inputs: node (required), vmid (required), snapname (required), confirm, +1 more. Returns: object

pve_set_vm_configC

Update VM/container config. Requires confirm=true.

Inputs: node (required), vmid (required), config (required), confirm, +1 more. Returns: object

pve_shutdown_vmB

Gracefully shut down a VM/container. Requires confirm=true.

Inputs: node (required), vmid (required), confirm, timeout, +2 more. Returns: object

pve_start_vmC

Start a VM/container. Requires confirm=true.

Inputs: node (required), vmid (required), confirm, vm_type. Returns: object

pve_stop_vmA

Hard stop a VM/container. Requires confirm=true.

Inputs: node (required), vmid (required), confirm, vm_type. Returns: object

pve_suspend_vmC

Suspend a VM/container. Requires confirm=true.

Inputs: node (required), vmid (required), confirm, vm_type. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    B3.1/5.0

    Scored across 28 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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.

    Resources

    Related MCP Connectors

    Related MCP Servers

    • nandi-proxmox-mcp

      NANDI-Services
      A
      license
      Not graded
      quality
      B
      maintenance
      An open-source MCP server for managing Proxmox environments, including nodes, virtual machines, and containers. It enables users to perform inventory checks, status monitoring, and control operations directly through MCP-compatible tools.
      102 npm
      2
      MIT

    • proxmox-mcp

      nrohozen
      A
      license
      B
      quality
      C
      maintenance
      An MCP server that exposes Proxmox VE node/cluster as tools for MCP clients, enabling management of VMs and containers including power control, resource reconfiguration, snapshots, and backups.
      20
      MIT