Proxmox MCP Server
MCP-сервер Proxmox VE с 341 инструментом: виртуальные машины, контейнеры, хранилища, кластер и бэкапы, с режимом только чтения.
- 77 ★ репозитория
- Последний коммит
Широкий доступ
Почему такой уровень
- Агент может останавливать, удалять и откатывать виртуальные машины и выполнять команды внутри гостей.
- Токен API Proxmox дает доступ ко всему кластеру в рамках прав пользователя.
Установка
- Работает в
Ручная установка
git clone https://github.com/ry-ops/proxmox-mcp-server && cd proxmox-mcp-serverЗатем `./setup.sh` или `uv sync`, переменные `PROXMOX_*` и проверка `./test-connection.sh`.
Доступ и проверки
Как мы проверяемШирокий доступИнструмент может менять данные, выполнять команды или работать с секретами.
- Агент может останавливать, удалять и откатывать виртуальные машины и выполнять команды внутри гостей.
- Токен API Proxmox дает доступ ко всему кластеру в рамках прав пользователя.
Это чужой код. Посмотрите файлы в репозитории перед установкой.
Что делает
Proxmox MCP Server отдает агенту весь API Proxmox VE: 341 инструмент в 14 областях. Узлы, виртуальные машины QEMU и контейнеры LXC, хранилища и бэкапы, кластер и HA, управление доступом, межсетевой экран, диски, Ceph, ACME, SDN, уведомления и пулы. Через гостевой агент QEMU можно выполнить команду внутри ВМ и прочитать код выхода и вывод. Для безопасности есть переключатели: `PROXMOX_READ_ONLY=true` оставляет клиенту только 150 инструментов чтения, `PROXMOX_NO_DESTRUCTIVE=true` прячет 73 инструмента удаления, остановки и отката, `PROXMOX_PROTECTED_VMIDS` называет ВМ, которые нельзя менять. Инструменты помечены подсказками `readOnlyHint` и `destructiveHint`, а `PROXMOX_AUDIT_LOG` пишет по строке JSON на каждую запись. Набор можно сузить через `PROXMOX_TOOLSETS`: например, до 127 инструментов вместо 341.
Для кого. Администраторам Proxmox VE и домашних лабораторий, которые хотят управлять кластером разговором с агентом, не заучивая вызовы API.
Подходит, если
- Нужна сводка по виртуальным машинам и использованию хранилищ на всех узлах.
- Перед обновлением делается снимок ВМ, затем изменение и проверка по рецепту из встроенного запроса.
- Клонируется шаблон и сразу запускается новая машина, а MCP ждет завершения задачи.
- Внутри гостя надо выполнить `df -h` и прочитать вывод через гостевой агент.
- Клиенту выдается только чтение для мониторинга с ролью `PVEAuditor`.
Не подходит, если
- Кластер продуктивный, а у токена полные права и нет защищенных ВМ: ошибка агента может удалить машину.
- Нужен только `qm` и `pct` на одном узле без токена API.
- Версия Proxmox VE ниже 6.0.
Пример запроса к агенту
Покажи все виртуальные машины в моем кластере Proxmox и использование хранилищ на каждом узле, ничего не меняй.MCP
- Транспорт
- stdio, http
- Авторизация
- API-ключ
Переменные окружения
PROXMOX_HOSTобязательная- Адрес сервера Proxmox VE.
PROXMOX_USERобязательная- Пользователь Proxmox, например `root@pam`.
PROXMOX_TOKEN_NAMEобязательная- Имя токена API.
PROXMOX_TOKEN_VALUEобязательная, секрет- Значение токена API.
PROXMOX_READ_ONLY- При `true` сервер отказывает во всех записях.
Ограничения
Нужны Proxmox VE 6.0 или новее и Python 3.10 с `uv`, либо Docker. Токен API создается в Datacenter, Permissions, API Tokens, а для полного доступа в нем отключают Privilege Separation: тогда токен получает права пользователя. Задайте `PROXMOX_HOST`, `PROXMOX_USER`, `PROXMOX_TOKEN_NAME` и `PROXMOX_TOKEN_VALUE`. Без режима только чтения агент может останавливать, удалять и откатывать машины и выполнять команды внутри гостей. Для мониторинга используйте токен с ролью `PVEAuditor` и `PROXMOX_READ_ONLY=true`.
Как отключить. Удалите запись `proxmox` из конфигурации MCP-клиента, остановите контейнер при запуске в Docker и отзовите токен в Datacenter, Permissions, API Tokens.
Частые вопросы
Как подключить Proxmox MCP Server?
Склонируйте репозиторий, выполните `./setup.sh` или `uv sync`, задайте переменные `PROXMOX_*` и добавьте в конфиг клиента команду `uv --directory /абсолютный/путь run proxmox-mcp-server`. Есть и образ `ghcr.io/ry-ops/proxmox-mcp-server:latest`.
Как сделать доступ только на чтение?
Задайте `PROXMOX_READ_ONLY=true`: сервер отказывает во всех записях, а клиент видит только 150 инструментов чтения. Для токена возьмите роль `PVEAuditor`.
Как защитить важные виртуальные машины?
Перечислите их в `PROXMOX_PROTECTED_VMIDS`, и ни один инструмент не изменит эти ВМ. Дополнительно `PROXMOX_NO_DESTRUCTIVE=true` скрывает 73 инструмента удаления, остановки и отката.
Как ждать медленные операции?
Клонирование, миграция, бэкап и восстановление принимают `wait: true`, а `wait_for_task` следит за любой задачей до конца и при ошибке показывает журнал.
Как сократить список инструментов?
Переменная `PROXMOX_TOOLSETS=nodes,qemu,lxc,storage` оставляет 127 инструментов вместо 341 и более чем вдвое сокращает расход контекста.
Обсуждение
Вопросов и отзывов пока нет.
Похожие
MCP-серверыMCP-сервер для Proxmox VE: управление виртуалками, LXC, снапшотами и бэкапами из агента с контролем прав и одобрением команд
MCP-сервер для Proxmox VE, Backup Server, Mail Gateway и Datacenter Manager: план до действия, журнал изменений и откат
Самохостящийся хаб для домашней лаборатории со встроенным MCP-сервером: у агента 32 инструмента с правами по ключам API
MCP Slim Guard стоит между агентом и вашими MCP-серверами: проверяет вызовы по схеме и отдает большие ответы частями.
WebSSH-консоль для VPS с MCP-сервером: агент работает на нескольких серверах, а токены с ACL ограничивают инструменты и хосты.
Самостоятельно размещаемый шлюз, который собирает несколько MCP-серверов в один эндпоинт с авторизацией и выбором инструментов
Коротко о README
Сервер запускается по stdio или через `proxmox-mcp-server-http` с токенами и ролями `read`, `operator` и `admin` на клиента. Он строится на MCP SDK 2 и поддерживает старые клиенты, а `agent-card.json` описывает инструменты для обнаружения между агентами.