proxmox-ve-mcp

Сервер MCP, который предоставляет один или несколько хостов Proxmox VE в виде инструментов, которые может вызывать LLM-клиент: инвентаризация узлов, гостевых систем, хранилищ и сетевых мостов, чтение текущего состояния, а также создание, клонирование, запуск, остановка и удаление виртуальных машин и контейнеров.

Он использует MCP через Streamable HTTP, поэтому работает как собственный сервис в сети, а не как локальный подпроцесс одного клиента.

Создан для universal-network-director, чат-ориентированного мультивендорного сетевого менеджера с этапом одобрения человеком для каждой операции записи — но это самостоятельный MCP-сервер и работает с любым MCP-клиентом.

Не аффилирован, не одобрен и не поддерживается компанией Proxmox Server Solutions GmbH. «Proxmox» и «Proxmox VE» являются товарными знаками соответствующих владельцев и используются здесь только для описания того, с чем взаимодействует это программное обеспечение.

Прочтите это, прежде чем направлять его на продуктивную среду

Двенадцать из двадцати четырех инструментов изменяют состояние, и этот сервер не спрашивает перед их выполнением. Нет подтверждения и нет пробного запуска. Если модель решает вызвать один из них, это происходит.

Три способа справиться с этим, в порядке их реальной полезности:

1. Ограничьте API-токен Proxmox только чтением. Это реальный контроль, и он находится на Proxmox, а не в этом коде. Дайте токену встроенную роль PVEAuditor на пути /, и каждый инструмент записи будет терпеть неудачу на уровне API, независимо от того, что решит любая модель. Делайте так, если вы специально не хотите, чтобы операции записи работали.

2. Используйте список запрещенных гостевых систем. config/protected-vms.json содержит гостевые системы, к которым инструменты записи отказываются прикасаться, проверка выполняется локально до любого вызова бэкенда — поэтому она действует, даже если человек случайно что-то одобрил. Отсутствующий или нечитаемый файл запрещает любую запись гостевой системы, а не молча ничего не защищает. См. ниже.

3. Ограничьте операции записи в вашем клиенте. Каждый инструмент, изменяющий состояние, имеет префикс write_. Этот префикс является соглашением данной кодовой базы именно для того, чтобы клиент мог сопоставлять его и направлять такие вызовы через этап одобрения человеком перед выполнением. Этот сервер намеренно не делает этого сам — у него нет пользователя, которого можно спросить.

Конечная точка MCP не имеет аутентификации

Этот сервер предоставляет свои инструменты любому, кто может достичь его порта. Нет токена, нет аутентификации клиента, нет TLS на стороне MCP.

MCP_HOST по умолчанию равен 127.0.0.1 по этой причине. Образ контейнера устанавливает 0.0.0.0, потому что это необходимо, что означает, что публикация порта контейнера открывает неаутентифицированную панель управления для ваших гипервизоров на этом интерфейсе. Держите его во внутренней сети с клиентом или завершайте TLS и аутентификацию перед ним.

Многопоточность по дизайну

Кластеры Proxmox используют один API, но многие конфигурации используют несколько автономных хостов в разных подсетях без кластеризации между ними. Этот сервер хранит одно соединение на хост, привязанное к короткой произвольной метке, и каждый инструмент использует эту метку для выбора хоста, с которым нужно взаимодействовать.

Хост определяется парой переменных окружения:

PROXMOX_SERVER1_URL=https://pve1.example.com:8006
PROXMOX_SERVER1_TOKEN='automation@pve!mcp=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

<МЕТКА> в PROXMOX_<МЕТКА>_URL, приведенная к нижнему регистру, становится значением host, которое принимают инструменты (server1 выше). Добавьте третий хост, добавив третью пару — без изменения кода. Называйте их по сайту, чтобы модель и логи читались четко.

Токен — это вся строка user@realm!tokenid=secret, показанная один раз при создании в разделе Datacenter → Permissions → API Tokens. Аутентификация не имеет состояния: каждый запрос несет заголовок Authorization: PVEAPIToken=.... Нет вызова входа в систему и нет CSRF-токена — это путь сессии с именем пользователя/паролем, который намеренно не используется.

Установите PROXMOX_VERIFY_TLS=false для хостов с самоподписанными сертификатами. По умолчанию включено.

Список запрещенных гостевых систем

config/protected-vms.json монтируется только для чтения в контейнер и содержит гостевые системы, к которым инструменты записи никогда не должны прикасаться:

{
  "protected_vms": [
    {
      "host": "server1",
      "vmid": 100,
      "name": "example-mcp-host",
      "reason": "EXAMPLE -- the VM this MCP server itself runs in"
    }
  ]
}

host — это метка из list_hosts, а не имя узла Proxmox. reason показывается дословно в отказе, поэтому пишите его для того, кто с ним столкнется.

Этот файл предназначен для отслеживания в git. Изначально он был переменной окружения в неотслеживаемом .env, что означало, что защита не сохранялась после свежего клонирования, а пустой список выглядел точно так же, как заполненный. Теперь отсутствующий или нечитаемый файл запрещает любую запись гостевой системы; пустой список разрешен, но выводит громкое предупреждение при запуске.

Записи, поставляемые здесь, являются примерами. Замените их, прежде чем направлять это на что-то, что вам дорого.

Запуск

docker build -t proxmox-ve-mcp .
docker run --rm \
  -e PROXMOX_SERVER1_URL=https://pve1.example.com:8006 \
  -e PROXMOX_SERVER1_TOKEN='automation@pve!mcp=...' \
  -e PROXMOX_VERIFY_TLS=false \
  -v "$PWD/config/protected-vms.json:/app/config/protected-vms.json:ro" \
  -p 127.0.0.1:8002:8002 \
  proxmox-ve-mcp

Или укажите pip install -r requirements.txt в virtualenv и запустите python server.py напрямую.

Тесты

Автономные скрипты, без pytest. Запускайте их в контейнере, чтобы они имели окружение PROXMOX_*, необходимое клиенту:

docker run --rm proxmox-ve-mcp python test_network_bridges.py
docker run --rm proxmox-ve-mcp python test_media_in_use.py
docker run --rm proxmox-ve-mcp python test_client.py

Автономные разделы используют вымышленные списки интерфейсов и гостевых систем и проходят без настроенных хостов. Разделы реального времени читают то, на что указывают ваши переменные PROXMOX_*, и чисто пропускаются, когда ничего не настроено — укажите их на реальный хост, чтобы проверить единственное различие, которое нельзя подделать: подключен ли мост к внешней сети или изолирован.

Заметки по дизайну

• /cluster/resources — основа инвентаризации. Один вызов возвращает каждую ВМ, контейнер, узел и хранилище, уже помеченные своим узлом, vmid и типом. Это работает и на автономном хосте (он сообщает об этом одном узле), поэтому используется вместо обхода /nodes → /nodes/{node}/qemu на каждый узел.

• list_network_bridges существует, потому что сетевой интерфейс не на том мосту — это гостевая система, до которой вы не можете добраться. Он сообщает, для каждого моста, есть ли у него порт-член (способ покинуть коробку) или это изолированный сегмент — различие, которое решает, будет ли новая ВМ доступна.

• Теги VLAN закрываются с ошибкой. tag= на мосту, который не является bridge_vlan_aware, принимается Proxmox, а затем молча не переносится — немаркированный трафик там, где требовалась изоляция. Пути записи отказывают в этом, а не предупреждают, и отказывают, если не могут прочитать список мостов для проверки.

• Операции записи асинхронны. Большинство возвращает UPID Proxmox; опрашивайте его с помощью get_task_status, а не предполагайте завершение.

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

Лицензия

Apache-2.0. См. LICENSE.