NANDI Proxmox MCP

Превратите свой кластер Proxmox в платформу на базе ИИ с более чем 140 инструментами для автоматизации, мониторинга и контролируемого выполнения задач.

MCP-сервер с открытым исходным кодом для Proxmox VE, работающий на базе NANDI Services.

nandi-proxmox-mcp предоставляет доступ к инвентаризации Proxmox, жизненному циклу, хранилищам, резервному копированию, сети, брандмауэру, доступу, мониторингу, SSH-диагностике и защищенным удаленным/контейнерным операциям без снятия защитных механизмов, необходимых для производственных кластеров.

Что остается включенным

140+ инструментов для работы с узлами, кластером, QEMU, LXC, хранилищами, резервным копированием, задачами, сетью, брандмауэром, пулами, доступом, шаблонами, мониторингом и удаленными операциями.
Уровни доступа: read-only, read-execute, full.
Разделение модулей: PVE_MODULE_MODE=core|advanced.
Фильтры инструментов: PVE_CATEGORIES, PVE_TOOL_BLACKLIST, PVE_TOOL_WHITELIST.
Защита от деструктивных действий через confirm=true.
Обратно совместимые псевдонимы, такие как listNodes, getVMStatus, startVM, stopContainer.
Транспорт stdio для MCP-клиентов и потоковый HTTP-транспорт для контролируемых удаленных развертываний.

Необходимые разрешения

Серверу требуются два канала доверия, и оба они намеренно сохранены:

API-токен Proxmox
- Используется для инвентаризации, жизненного цикла, конфигурации и конечных точек управления.
- Сохраняйте списки контроля доступа (ACL) минимальными: предоставляйте только те роли, которые необходимы для инструментов, которые вы действительно используете.
SSH-доступ к хосту Proxmox
- Требуется для pct exec, пакетной SSH-диагностики и инструментов проверки Docker на уровне контейнеров.
- Это по-прежнему необходимо, поскольку покрытие API Proxmox не заменяет pct на стороне хоста и диагностику на основе SSH.

Подробнее: docs/PERMISSIONS.md

Подтверждение деструктивных действий

Операции, помеченные как деструктивные, не выполняются, если вызывающая сторона не отправит confirm=true.

Примеры:

Остановка, выключение, перезагрузка, приостановка, удаление, миграция, откат снимка (snapshot) ВМ/контейнера
Запись в хранилище/сеть/брандмауэр/доступ, которая может изменить состояние кластера
Расширенное удаленное выполнение, такое как pve_exec_in_container

Сервер возвращает структурированную ошибку CONFIRMATION_REQUIRED, если подтверждение отсутствует. Это поведение неизменно и усилено.

Уровни доступа

read-only
- Инвентаризация, статус, журналы, метрики и диагностика без внесения изменений.
read-execute
- Только чтение плюс выбранные действия по выполнению/жизненному циклу.
full
- Создание, обновление, удаление, миграция, восстановление и операции административного уровня.

PVE_MODULE_MODE=core скрывает расширенные инструменты, не переименовывая и не удаляя канонические идентификаторы инструментов из кодовой базы.

Конфигурация среды выполнения

Переменные окружения

Обязательные:

PROXMOX_HOST
PROXMOX_USER
PROXMOX_REALM
PROXMOX_TOKEN_NAME
PROXMOX_TOKEN_SECRET
PROXMOX_SSH_HOST
PROXMOX_SSH_USER
PROXMOX_SSH_KEY_PATH

Опциональные:

PROXMOX_PORT по умолчанию 8006
PROXMOX_SSH_PORT по умолчанию 22
PROXMOX_ALLOW_INSECURE_TLS по умолчанию false
PVE_ACCESS_TIER=read-only|read-execute|full
PVE_MODULE_MODE=core|advanced
PVE_CATEGORIES
PVE_TOOL_BLACKLIST
PVE_TOOL_WHITELIST

HTTP-транспорт:

MCP_TRANSPORT=stdio|http
MCP_HOST по умолчанию 0.0.0.0
MCP_PORT по умолчанию 3000
MCP_ALLOWED_HOSTS
MCP_ALLOWED_ORIGINS
MCP_RATE_LIMIT_WINDOW_MS
MCP_RATE_LIMIT_MAX
MCP_MAX_BODY_SIZE_BYTES
MCP_HEADERS_TIMEOUT_MS
MCP_REQUEST_TIMEOUT_MS
MCP_KEEPALIVE_TIMEOUT_MS
MCP_MAX_HEADERS_COUNT

Локальный файл конфигурации

Установка записывает .nandi-proxmox-mcp/config.json и .vscode/mcp.json.

Загрузчик конфигурации теперь отклоняет:

пустые или некорректные пути к конфигурации
слишком большие файлы конфигурации
управляющие символы в путях к конфигурации

Быстрый старт

Пошаговая настройка:

npx nandi-proxmox-mcp setup
npx nandi-proxmox-mcp doctor --check mcp-config,nodes,vms,cts,node-status,remote-op

Прямой запуск с переменными окружения:

$env:PROXMOX_HOST="pve.local"
$env:PROXMOX_PORT="8006"
$env:PROXMOX_USER="svc_mcp"
$env:PROXMOX_REALM="pve"
$env:PROXMOX_TOKEN_NAME="nandi-mcp"
$env:PROXMOX_TOKEN_SECRET="<SECRET>"
$env:PROXMOX_SSH_HOST="pve.local"
$env:PROXMOX_SSH_USER="root"
$env:PROXMOX_SSH_KEY_PATH="$env:USERPROFILE\.ssh\id_ed25519"

npx nandi-proxmox-mcp run

Модель безопасности и остаточные риски

Этот MCP-сервер работает с реальной инфраструктурой Proxmox и не является изолированной средой (песочницей).

Предположения о доверии

Сервер развернут в доверенной среде
Доступ к нему имеют только авторизованные операторы
Сетевое воздействие контролируется (не открыт для публичного доступа)
Учетные данные надежно защищены

Остаточные риски

Следующие риски присущи архитектуре системы:

Привилегированные операции Уровень полного доступа и возможности выполнения команд в контейнерах позволяют выполнять деструктивные действия или действия системного уровня.
Граница выполнения SSH Удаленное выполнение команд опирается на SSH и наследует уровень безопасности целевой системы.
Опциональный небезопасный режим TLS При включении (PROXMOX_ALLOW_INSECURE_TLS=true) проверка TLS-сертификатов обходится, что может подвергнуть соединения атакам типа MITM. Предназначено только для лабораторного использования.
Синхронизация внешних зависимостей Распространение пакетов и видимость в списках зависят от npm, реестра MCP и времени распространения на маркетплейсах.

Обязанности по обеспечению безопасности

Пользователи несут ответственность за:

Ограничение доступа только доверенными операторами
Использование API-токенов и SSH-ключей с минимальными привилегиями
Отказ от использования небезопасного TLS в производственных средах
Надлежащую защиту базовой инфраструктуры

Внедренные средства контроля безопасности

Уровни доступа (read-only, read-execute, full)
Обязательное подтверждение для деструктивных операций
Валидация входных данных и усиление команд
Ограничение частоты запросов (rate limiting) и их валидация

Усиление HTTP

Когда включен MCP_TRANSPORT=http, сервер применяет:

принудительное использование списка разрешенных хостов, включая защиту от привязки к подстановочным знакам (wildcard-bind)
проверку источника (origin) для запросов, отправляющих заголовок Origin
явные ограничения размера тела запроса и очищенные ответы 413
ограничение частоты запросов на /mcp
тайм-ауты запросов/заголовков/keep-alive
X-Content-Type-Options: nosniff
Cache-Control: no-store
очищенные полезные нагрузки ошибок без трассировки стека

Конечные точки состояния (health/readiness):

GET /health
GET /ready
POST /mcp

Усиление SSH и выполнения команд

Функциональность не изменилась, но путь выполнения стал строже:

локальное выполнение команд по-прежнему использует spawn(..., { shell: false })
значения SSH-хоста/пользователя не могут содержать скрытые CLI-опции
SSH использует BatchMode, IdentitiesOnly, аутентификацию по открытому ключу и явный контроль активности соединения
буферы вывода ограничены для предотвращения неограниченного роста памяти
dockerLogsInContainer теперь проверяет и экранирует имена контейнеров вместо интерполяции необработанного ввода пользователя
произвольное выполнение команд в контейнере остается доступным только через уже деструктивный поток pve_exec_in_container с обязательным подтверждением

Состояние безопасности

Меры по смягчению рисков в репозитории:

закрепленные версии прямых зависимостей и overrides в npm для критических транзитивных пакетов
проверяемые метаданные пакетов и ссылки на репозитории для сканеров npm/пакетов
проверка синхронизации дескриптора/версии для артефактов npm, реестра и маркетплейса
удаление значений, похожих на токены/заголовки/пароли, из журналов
клиентам не возвращаются трассировки стека или секреты
CI-шлюзы для линтинга, проверки типов, сборки, тестов, проверки метаданных, синхронизации дескрипторов, npm pack --dry-run и аудита

Модель угроз и остаточные риски: docs/THREAT_MODEL.md

Процесс публикации

Порядок выпуска строгий:

npm run lint
npm run typecheck
npm run build
npm test
npm audit --include=dev --audit-level=moderate
npm ls express
npm ls path-to-regexp
npm pack --dry-run
npm pack
npm whoami
npm publish --access public
npm view nandi-proxmox-mcp version
mcp-publisher validate .mcp/server.json
mcp-publisher publish .mcp/server.json

Файл release.yml на основе тегов теперь сначала публикует npm и только потом дескриптор реестра MCP, предотвращая расхождение версий npm/реестра.

Ручной откат и устранение неполадок: docs/RELEASE.md

Разработка

npm ci
npm run lint
npm run typecheck
npm run build
npm test
npm run validate:release
npm pack --dry-run

Политика ведения документации

Этот репозиторий обеспечивает шлюз синхронизации документации перед коммитом.

Перед закрытием change, fix или refactor оцените, нужно ли обновлять README.md, AGENTS.md и CONTRIBUTING.md.
Если документ относится к поведенческому или процессуальному воздействию, он должен быть обновлен в том же наборе изменений.
Если обновление не требуется, необходимо явное обоснование no-doc-change.
Задача не считается готовой к коммиту, пока этот шлюз не пройден.

Документация

Реестр и маркетплейс

npm: https://www.npmjs.com/package/nandi-proxmox-mcp
Реестр MCP: https://registry.modelcontextprotocol.io/
Список на маркетплейсе MCP: https://mcp-marketplace.io/server/io-github-nandi-services-nandi-proxmox-mcp

Лицензия

MIT. См. LICENSE.

nandi-proxmox-mcp