# Установка Proxmox MCP-сервера и подключение к Open WebUI

Инструкция под твою инфраструктуру: **pve** (192.168.31.2), **kybinka** (192.168.1.10), **pve1** (192.168.31.4), **TrueNAS** (192.168.31.100, там же работает Open WebUI).

Используем проект **ProxmoxMCP-Plus**. Для Open WebUI применяется его OpenAPI-интерфейс.

## ⚠️ Важный момент про архитектуру

Узлы `pve`, `kybinka` и `pve1` — независимые Proxmox-серверы. Для каждого узла требуется отдельный контейнер MCP с отдельным портом.

---

## Шаг 1. Создать API-токен на каждом Proxmox-узле

Токен создаётся отдельно на каждом узле.

1. Открой веб-интерфейс узла, например `https://192.168.31.2:8006`.
2. Перейди в **Datacenter → Permissions → API Tokens**.
3. Нажми **Add**:
   - User: `root@pam`;
   - Token ID: `openwebui-token`;
   - отключи **Privilege Separation**, если используешь права пользователя напрямую.
4. Сохрани **Token ID** и **Secret**. Secret показывается только один раз.

Повтори для `kybinka` и `pve1`. В конфигурацию нужно подставить секрет токена соответствующего узла.

---

## Шаг 2. Подготовить конфиги на TrueNAS

Файлы конфигурации должны находиться в следующих каталогах:

```text
/mnt/ssd/apps/mcp/pve/config.json
/mnt/ssd/apps/mcp/kybinka/config.json
/mnt/ssd/apps/mcp/pve1/config.json
```

Если каталоги ещё не созданы, выполни на TrueNAS через SSH или Shell:

```bash
mkdir -p /mnt/ssd/apps/mcp/{pve,kybinka,pve1}
```

> В каждом файле должен быть секрет API-токена именно соответствующего Proxmox-узла. Не оставляй текст `СЮДА_СЕКРЕТ_ТОКЕНА_*` в рабочем конфиге.

### Конфигурация узла `pve`

Создай файл `/mnt/ssd/apps/mcp/pve/config.json`:

```bash
cat > /mnt/ssd/apps/mcp/pve/config.json << 'EOF'
{
  "dev_mode": true,
  "proxmox": {
    "host": "192.168.31.2",
    "port": 8006,
    "verify_ssl": false
  },
  "auth": {
    "user": "root@pam",
    "token_name": "openwebui-token",
    "token_value": "СЮДА_СЕКРЕТ_ТОКЕНА_PVE"
  },
  "logging": {
    "level": "INFO"
  }
}
EOF
```

### Конфигурация узла `kybinka`

Создай файл `/mnt/ssd/apps/mcp/kybinka/config.json`:

```bash
cat > /mnt/ssd/apps/mcp/kybinka/config.json << 'EOF'
{
  "dev_mode": true,
  "proxmox": {
    "host": "192.168.1.10",
    "port": 8006,
    "verify_ssl": false
  },
  "auth": {
    "user": "root@pam",
    "token_name": "openwebui-token",
    "token_value": "СЮДА_СЕКРЕТ_ТОКЕНА_KYBINKA"
  },
  "logging": {
    "level": "INFO"
  }
}
EOF
```

### Конфигурация узла `pve1`

Создай файл `/mnt/ssd/apps/mcp/pve1/config.json`:

```bash
cat > /mnt/ssd/apps/mcp/pve1/config.json << 'EOF'
{
  "dev_mode": true,
  "proxmox": {
    "host": "192.168.31.4",
    "port": 8006,
    "verify_ssl": false
  },
  "auth": {
    "user": "root@pam",
    "token_name": "openwebui-token",
    "token_value": "СЮДА_СЕКРЕТ_ТОКЕНА_PVE1"
  },
  "logging": {
    "level": "INFO"
  }
}
EOF
```

Проверь корректность всех JSON-файлов до запуска контейнеров:

```bash
python3 -m json.tool /mnt/ssd/apps/mcp/pve/config.json
python3 -m json.tool /mnt/ssd/apps/mcp/kybinka/config.json
python3 -m json.tool /mnt/ssd/apps/mcp/pve1/config.json
```

Если ошибок нет, команды выведут отформатированное содержимое JSON. При необходимости ограничь права доступа к файлам с токенами:

```bash
chmod 600 /mnt/ssd/apps/mcp/{pve,kybinka,pve1}/config.json
```

> `verify_ssl: false` отключает проверку TLS-сертификата Proxmox. Параметр `dev_mode: true` требуется текущей версией ProxmoxMCP-Plus, чтобы разрешить такое подключение с самоподписанным сертификатом. Для production лучше установить доверенный сертификат и использовать `verify_ssl: true` вместе с `dev_mode: false`.

---

## Шаг 3. Запустить три контейнера через Dockge

В Dockge создай один Stack с именем `proxmox-mcp`.

1. Открой Dockge.
2. Нажми **Create Stack** или **+**.
3. Укажи имя `proxmox-mcp`.
4. Укажи рабочую директорию стека:

   `/mnt/ssd/apps/mcp`

5. Вставь в compose-редактор:

```yaml
services:
  proxmox-mcp-pve:
    image: ghcr.io/rekklesna/proxmoxmcp-plus:latest
    container_name: proxmox-mcp-pve
    restart: unless-stopped
    ports:
      - "8811:8811"
    environment:
      PROXMOX_API_KEY: ключ-для-pve-придумай-любой-длинный
    volumes:
      - /mnt/ssd/apps/mcp/pve/config.json:/app/proxmox-config/config.json:ro

  proxmox-mcp-kybinka:
    image: ghcr.io/rekklesna/proxmoxmcp-plus:latest
    container_name: proxmox-mcp-kybinka
    restart: unless-stopped
    ports:
      - "8812:8811"
    environment:
      PROXMOX_API_KEY: ключ-для-kybinka-придумай-любой-длинный
    volumes:
      - /mnt/ssd/apps/mcp/kybinka/config.json:/app/proxmox-config/config.json:ro

  proxmox-mcp-pve1:
    image: ghcr.io/rekklesna/proxmoxmcp-plus:latest
    container_name: proxmox-mcp-pve1
    restart: unless-stopped
    ports:
      - "8813:8811"
    environment:
      PROXMOX_API_KEY: ключ-для-pve1-придумай-любой-длинный
    volumes:
      - /mnt/ssd/apps/mcp/pve1/config.json:/app/proxmox-config/config.json:ro
```

6. Замени значения `ключ-для-*` на свои ключи.
7. Нажми **Save**, затем **Deploy** / **Up** / **Start**.

В результате должны запуститься контейнеры `proxmox-mcp-pve`, `proxmox-mcp-kybinka` и `proxmox-mcp-pve1` на портах `8811`, `8812` и `8813` соответственно.

---

## Шаг 4. Проверить, что контейнеры работают

```bash
curl -f http://192.168.31.100:8811/livez   # pve
curl -f http://192.168.31.100:8812/livez   # kybinka
curl -f http://192.168.31.100:8813/livez   # pve1
```

Авторизованный запрос:

```bash
curl -H "Authorization: Bearer ключ-для-pve" http://192.168.31.100:8811/health
```

---

## Шаг 5. Подключить к Open WebUI

В Open WebUI добавь три OpenAPI Tool Server:

- `http://192.168.31.100:8811/openapi.json` — `Proxmox pve`;
- `http://192.168.31.100:8812/openapi.json` — `Proxmox kybinka`;
- `http://192.168.31.100:8813/openapi.json` — `Proxmox pve1`.

Для каждого сервера укажи свой Bearer-ключ из `PROXMOX_API_KEY` в compose-конфигурации Dockge.

---

## Частые проблемы

| Симптом | Причина |
| --- | --- |
| `logging Field required` | В контейнер попал старый `config.json` без блока `logging` или подключён неправильный файл через volume |
| `Insecure TLS configuration blocked` | В конфигурации отсутствует `dev_mode: true` при использовании `verify_ssl: false` |
| `McpError: Connection closed` | MCP-сервер завершился из-за ошибки конфигурации; исправь первичную ошибку выше по логу |
| Контейнер падает при старте | Невалидный JSON или неверный путь к `config.json` |
| `401 Unauthorized` | Bearer-ключ не совпадает с `PROXMOX_API_KEY` |
| Инструмент не появляется в Open WebUI | Проверь URL `/openapi.json` и доступность соответствующего порта |
| Модель не видит VM | Проверь права API-токена Proxmox и логи контейнера в Dockge |

Если после изменения конфигурации остаётся ошибка `logging Field required`, останови Stack в Dockge, проверь файлы на TrueNAS и заново выполни **Deploy**. В compose должны использоваться именно эти volume-маунты:

```yaml
- /mnt/ssd/apps/mcp/pve/config.json:/app/proxmox-config/config.json:ro
- /mnt/ssd/apps/mcp/kybinka/config.json:/app/proxmox-config/config.json:ro
- /mnt/ssd/apps/mcp/pve1/config.json:/app/proxmox-config/config.json:ro
```