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-транспорт для контролируемых удаленных развертываний.

Related MCP server: ProxmoxMCP

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

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

• 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

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

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

1. npm run lint

2. npm run typecheck

3. npm run build

4. npm test

5. npm audit --include=dev --audit-level=moderate

6. npm ls express

7. npm ls path-to-regexp

8. npm pack --dry-run

9. npm pack

10. npm whoami

11. npm publish --access public

12. npm view nandi-proxmox-mcp version

13. mcp-publisher validate .mcp/server.json

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

• Задача не считается готовой к коммиту, пока этот шлюз не пройден.

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

• docs/QUICKSTART.md

• docs/PERMISSIONS.md

• docs/SECURITY.md

• docs/THREAT_MODEL.md

• docs/RELEASE.md

• docs/TROUBLESHOOTING.md

• docs/TOOLS.md

• docs/MARKETPLACE_GO_LIVE.md

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

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