proxmox-mcp-setup/proxmox-mcp-open-webui-setup.md

# Установка 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** с OpenAPI-интерфейсом для Open WebUI.

## Архитектура

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

---

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

На каждом Proxmox-сервере отдельно открой **Datacenter → Permissions → API Tokens** и создай токен.

- User: `root@pam`;
- Token ID: например `openwebui-token`;
- сохрани Secret, который показывается только один раз;
- Token ID должен точно совпадать со значением `auth.token_name` в конфигурации.

Повтори операцию для `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
```

Создай каталоги:

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

> Важно: `dev_mode` находится внутри блока `security`, а не в корне JSON. Именно такую структуру ожидает ProxmoxMCP-Plus.

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

```json
{
  "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"
  },
  "security": {
    "dev_mode": true
  }
}
```

Сохрани этот JSON в `/mnt/ssd/apps/mcp/pve/config.json`.

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

```json
{
  "proxmox": {
    "host": "192.168.1.10",
    "port": 8006,
    "verify_ssl": false
  },
  "auth": {
    "user": "root@pam",
    "token_name": "open-webui",
    "token_value": "СЕКРЕТНЫЙ_ТОКЕН_KYBINKA"
  },
  "logging": {
    "level": "INFO"
  },
  "security": {
    "dev_mode": true
  }
}
```

Сохрани этот JSON в `/mnt/ssd/apps/mcp/kybinka/config.json`.

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

```json
{
  "proxmox": {
    "host": "192.168.31.4",
    "port": 8006,
    "verify_ssl": false
  },
  "auth": {
    "user": "root@pam",
    "token_name": "open-webui",
    "token_value": "СЕКРЕТНЫЙ_ТОКЕН_PVE1"
  },
  "logging": {
    "level": "INFO"
  },
  "security": {
    "dev_mode": true
  }
}
```

Сохрани этот JSON в `/mnt/ssd/apps/mcp/pve1/config.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
```

Ограничь доступ к файлам с токенами:

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

`verify_ssl: false` используется для самоподписанных сертификатов Proxmox. В этом случае требуется `security.dev_mode: true`. Для production следует установить доверенный сертификат и использовать `verify_ssl: true`, `security.dev_mode: false`.

---

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

В Dockge создай один Stack с именем `proxmox-mcp`, рабочая директория:

```text
/mnt/ssd/apps/mcp
```

Вставь в редактор Dockge **один** 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
```

Не добавляй несколько блоков `services:` подряд. `networks: {}` не требуется — Compose создаст сеть автоматически.

Замени `ЗАМЕНИТЬ_КЛЮЧ_*` на отдельные ключи для OpenAPI-доступа, нажми **Save**, затем **Down** и **Deploy/Up**. После изменения JSON-файлов контейнеры нужно перезапустить или пересоздать.

---

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

```bash
curl -f http://192.168.31.100:8811/livez
curl -f http://192.168.31.100:8812/livez
curl -f http://192.168.31.100:8813/livez
```

Проверка авторизации OpenAPI:

```bash
curl -H "Authorization: Bearer ЗАМЕНИТЬ_КЛЮЧ_PVE" \
  http://192.168.31.100:8811/health
```

---

## Шаг 5. Подключить к 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`.

---

## Диагностика

Если в логе появляется:

```text
Insecure TLS configuration blocked
```

проверь, что внутри контейнера присутствует именно такая структура:

```json
"security": {
  "dev_mode": true
}
```

Проверка маунта:

```bash
docker inspect proxmox-mcp-pve \
  --format '{{range .Mounts}}{{println .Source "->" .Destination}}{{end}}'
```

Ожидаемый результат:

```text
/mnt/ssd/apps/mcp/pve/config.json -> /app/proxmox-config/config.json
```

Проверка файла внутри контейнера:

```bash
docker exec proxmox-mcp-pve cat /app/proxmox-config/config.json
```

`McpError: Connection closed` является вторичной ошибкой: MCP OpenAPI Proxy закрывается после ошибки валидации конфигурации.

> Никогда не публикуй в чат или репозиторий реальные значения `PROXMOX_API_KEY` и `auth.token_value`. Если ключи уже были опубликованы, их следует заменить.