Proxmox-mcp

Простой Proxmox MCP

MCP-сервер для управления Proxmox VE

38 инструментов — узлы, виртуальные машины QEMU, контейнеры LXC, хранилища, кластер, снимки.

Почему именно этот?

• Один образ, мультиархитектурный — docker run ghcr.io/akmalovaa/proxmox-mcp:latest и готово

• Только переменные окружения — никаких файлов конфигурации, баз данных или состояний

• По умолчанию «только чтение» — деструктивные операции защищены явным параметром PROXMOX_RISK_LEVEL

• Минималистичный код — чистый stdio MCP поверх Proxmoxer, без HTTP-сервера, уровня аутентификации и лишних компонентов

• Вывод в формате Raw JSON — без форматирования и эмодзи; LLM получает «чистые» данные

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

Образ: ghcr.io/akmalovaa/proxmox-mcp:latest (мультиархитектурный: amd64 + arm64).

1. Экспортируйте учетные данные в профиле вашей оболочки (~/.zprofile, ~/.zshrc или ~/.bashrc):

# base environment:
export PROXMOX_HOST=192.168.1.100
export PROXMOX_USER=root@pam
export PROXMOX_PASSWORD=your-password

# or use token auth (recommended):
export PROXMOX_TOKEN_NAME=mcp
export PROXMOX_TOKEN_VALUE=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

# optional:
export PROXMOX_RISK_LEVEL=read

Перезагрузите: source ~/.zprofile (или перезапустите оболочку).

2. Добавьте в ~/.claude/settings.json (Claude Code) или claude_desktop_config.json (Claude Desktop)`:

{
  "mcpServers": {
    "proxmox": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-e", "PROXMOX_HOST",
        "-e", "PROXMOX_USER",
        "-e", "PROXMOX_PASSWORD",
        "ghcr.io/akmalovaa/proxmox-mcp:latest"]
    }
  }
}

или аутентификация по токену:

{
  "mcpServers": {
    "proxmox": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
        "-e", "PROXMOX_HOST",
        "-e", "PROXMOX_USER",
        "-e", "PROXMOX_TOKEN_NAME",
        "-e", "PROXMOX_TOKEN_VALUE",
        "ghcr.io/akmalovaa/proxmox-mcp:latest"]
    }
  }
}

Команда docker run -e VAR без значения передает переменную хоста — никаких секретов в файле конфигурации. Перезапустите клиент — и 38 инструментов Proxmox станут доступны.

Для аутентификации по паролю замените переменные токена на PROXMOX_PASSWORD.

Примечание: Claude Desktop на macOS запускается через launchd и не наследует ~/.zprofile/~/.zshrc. Либо добавьте экспорт в ~/.zshenv, либо используйте встроенный блок "env": { ... } в конфигурации.

Конфигурация

Все настройки задаются через переменные окружения — укажите их в профиле оболочки, передайте встроенно в docker run -e или объявите в блоке env вашего MCP-клиента.

Аутентификация: токен или пароль

Выберите один вариант. Если заданы оба, приоритет у токена.

Токен (рекомендуется) — создайте в интерфейсе Proxmox: Datacenter → Permissions → API Tokens → Add (снимите галочку Privilege Separation). Затем:

export PROXMOX_TOKEN_NAME=mcp
export PROXMOX_TOKEN_VALUE=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Пароль (резервный вариант):

export PROXMOX_PASSWORD=your-password

Уровни риска

PROXMOX_RISK_LEVEL ограничивает деструктивные операции:

Каждый вызов с повышенными правами записывается в stderr (ALLOW / DENY + инструмент + уровень).

Инструменты

Узлы (7)

Виртуальные машины QEMU (14)

Контейнеры LXC (11)

Хранилища (2)

Кластер (4)

Архитектура

src/proxmox_mcp/
├── server.py    # FastMCP instance + entry point
├── config.py    # Pydantic Settings (PROXMOX_ prefix)
├── client.py    # Proxmoxer connection via lifespan
└── tools/       # nodes, vms, containers, storage, cluster

• По умолчанию «только чтение» — инструменты с повышенными правами защищены PROXMOX_RISK_LEVEL

• Единое соединение — клиент Proxmoxer создается один раз при запуске и используется совместно в течение жизненного цикла

• Вывод в формате Raw JSON — без форматирования; LLM получает данные напрямую

Разработка

Запуск в автономном режиме (тестирование)

export PROXMOX_HOST=192.168.1.100
export PROXMOX_USER=root@pam
export PROXMOX_TOKEN_NAME=mcp
export PROXMOX_TOKEN_VALUE=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

docker run -i --rm \
  -e PROXMOX_HOST -e PROXMOX_USER \
  -e PROXMOX_TOKEN_NAME -e PROXMOX_TOKEN_VALUE \
  ghcr.io/akmalovaa/proxmox-mcp:latest

Без Docker (UV)

git clone https://github.com/akmalovaa/proxmox-mcp.git && cd proxmox-mcp && uv sync

Конфигурация MCP-клиента:

{
  "mcpServers": {
    "proxmox": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/proxmox-mcp", "proxmox-mcp"],
      "env": {
        "PROXMOX_HOST": "192.168.1.100",
        "PROXMOX_TOKEN_NAME": "mcp",
        "PROXMOX_TOKEN_VALUE": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
      }
    }
  }
}

Сборка из исходного кода

git clone https://github.com/akmalovaa/proxmox-mcp.git
cd proxmox-mcp
docker build -t proxmox-mcp .

Лицензия

MIT