Unraid MCP

Локальный сервер Model Context Protocol, который позволяет ИИ-клиентам просматривать и управлять сервером Unraid через официальный GraphQL API Unraid.

Раскрытие информации об ИИ-ассистированной разработке: Этот проект был спроектирован, исследован, реализован, документирован и протестирован при существенной помощи ИИ-агентов по написанию кода. Это не официальный проект Unraid. Самостоятельно изучите исходный код, разрешения и настройки безопасности перед тем, как предоставлять ему доступ к серверу Unraid, особенно перед включением инструментов мутации.

MCP по умолчанию доступен только для чтения. Инструменты мутации полностью исключаются, пока они явно не включены через переменные окружения, а необратимые/высокорисковые действия имеют дополнительный уровень защиты.

Требования

• Node.js 22 или новее

• pnpm 11

• Unraid 7.2 или новее, где API встроен в ОС

• Ключ API Unraid

Unraid 7.0–7.1 может предоставлять API v4 через плагин Unraid Connect, но Unraid документирует эту комбинацию как ограниченную поддержку. GraphQL-документы в этом проекте ориентированы на API v4.35.1, входящий в состав Unraid 7.3.2. Более старые версии API могут отклонять новые запросы, такие как метрики, журналы или поля UPS.

Related MCP server: GraphQL MCP Toolkit

Настройка Unraid

1. Откройте Settings > Management Access > API Keys в веб-интерфейсе Unraid.

2. Создайте ключ для этого MCP.

3. Начните с роли VIEWER для доступа только для чтения.

4. Сохраните сгенерированный ключ в UNRAID_API_KEY; никогда не помещайте его в систему контроля версий или аргументы командной строки.

Эквивалентная команда в терминале Unraid:

unraid-api apikey --create --name "Unraid MCP read only" --roles VIEWER --json

Для доступа с мутациями отдавайте предпочтение детальным разрешениям, а не ADMIN. Выбирайте только те ресурсы, которые используются инструментами, которые вы планируете включить, например ARRAY, DOCKER, VMS и NOTIFICATIONS, с правами READ_ANY, UPDATE_ANY и только там, где это необходимо, DELETE_ANY.

GraphQL Sandbox не требуется для этого MCP. Оставьте его отключенным вне разработки, поскольку его включение также включает интроспекцию схемы.

Установка

pnpm install --frozen-lockfile
pnpm build

Зависимости закреплены по точным версиям, а установки выполняются с замороженным lockfile-файлом. pnpm также отклоняет релизы, опубликованные менее семи дней назад (включая пакеты с отсутствующим временем публикации), проверяет целостность пакетов/хранилища, блокирует необъявленные скрипты жизненного цикла и отказывается от понижения уровня доверия к пакетам. Исключение доверия для конкретной версии undici-types@6.21.0 требуется закреплённым @types/node; проверки возраста, целостности и lockfile-файла по-прежнему применяются к нему. Чтобы намеренно обновить зависимость после её проверки и ожидания карантинного периода, используйте точную версию и явно разрешите изменение lockfile-файла:

pnpm update --exact --no-frozen-lockfile package-name@x.y.z
pnpm verify
pnpm audit

Проверьте как package.json, так и pnpm-lock.yaml перед принятием обновления. Не добавляйте автоматические задания по обновлению зависимостей без сохранения этих мер контроля.

Задайте конфигурацию в окружении, которое запускает MCP:

export UNRAID_URL="https://tower.local"
export UNRAID_API_KEY="your-api-key"
node /absolute/path/to/unraid-mcp/dist/index.js

UNRAID_URL может быть источником веб-интерфейса, и в этом случае добавляется /graphql, или точной конечной точкой GraphQL. Настройте конечный HTTPS-URL напрямую; перенаправления отклоняются, чтобы ключ API не мог быть передан другому источнику.

Образ контейнера

Версионированные образы релизов публикуются на Docker Hub для linux/amd64 и linux/arm64. Для развёртываний закрепляйте версию или дайджест образа, а не полагайтесь на изменяемый тег latest:

docker pull lemanjo/unraid-mcp:0.1.1

Финальный образ использует среду выполнения Node.js Distroless с закреплённым дайджестом. Он работает без оболочки, менеджера пакетов, npm или других инструментов сборки и под числовым непривилегированным пользователем. Сборки контейнеров сканируются с помощью Trivy и завершаются ошибкой до входа в реестр при наличии исправимой критической или высокой уязвимости.

Соберите производственный образ на вашем сервере Unraid или другом Docker-хосте:

docker build --tag unraid-mcp:0.1.1 .

Локальный stdio-контейнер

Транспорт по умолчанию — stdio. --env NAME передаёт значения из запускающего окружения, не помещая секреты в образ или аргументы команды:

export UNRAID_URL="https://tower.local"
export UNRAID_API_KEY="your-api-key"

docker run --rm -i \
  --env UNRAID_URL \
  --env UNRAID_API_KEY \
  unraid-mcp:0.1.1

Передавайте любую дополнительную конфигурацию аналогичным образом, например --env UNRAID_ALLOW_MUTATIONS. Для пользовательского файла CA смонтируйте его только для чтения и настройте его путь в контейнере:

docker run --rm -i \
  --env UNRAID_URL \
  --env UNRAID_API_KEY \
  --env UNRAID_CA_CERT_PATH=/certs/unraid-ca.pem \
  --volume /host/path/unraid-ca.pem:/certs/unraid-ca.pem:ro \
  unraid-mcp:0.1.1

В режиме stdio образ не прослушивает порт. ИИ-хост запускает его с помощью docker run --rm -i и управляет его жизненным циклом.

Постоянно работающий удалённый HTTP-контейнер

Используйте аутентифицированный Streamable HTTP, когда контейнер работает на другой машине, чем ИИ-клиент. Сгенерируйте постоянный MCP-токен на доверенной машине:

export MCP_AUTH_TOKEN="$(openssl rand -hex 32)"
export UNRAID_URL="https://tower.local"
export UNRAID_API_KEY="your-unraid-api-key"
export MCP_ALLOWED_HOSTS="mcp-server.example,192.168.1.20"

Запустите удалённый контейнер:

docker network create unraid-mcp-backend

docker run -d \
  --name unraid-mcp \
  --restart unless-stopped \
  --network unraid-mcp-backend \
  --env MCP_TRANSPORT=http \
  --env MCP_HOST=0.0.0.0 \
  --env MCP_PORT=3000 \
  --env MCP_ALLOWED_HOSTS \
  --env MCP_AUTH_TOKEN \
  --env UNRAID_URL \
  --env UNRAID_API_KEY \
  unraid-mcp:0.1.1

MCP_ALLOWED_HOSTS обязателен при привязке к wildcard-адресу IPv4 или IPv6. Перечислите каждое имя хоста или IP-адрес, которые клиенты или обратный прокси будут помещать в HTTP-заголовок Host. Записи не включают порты, а записи IPv6 используют квадратные скобки. Значения localhost всегда включаются для проверок работоспособности.

Если MCP_AUTH_TOKEN опущен, сервер генерирует криптографически случайный 256-битный токен и выводит его один раз при запуске:

docker logs unraid-mcp

Ищите Generated MCP auth token:. Любой, кто может прочитать этот журнал, может получить доступ к MCP, а при каждом перезапуске процесса генерируется новый токен, если переменная остаётся неустановленной. Задайте MCP_AUTH_TOKEN явно для стабильных производственных развёртываний. MCP-токен отделён от UNRAID_API_KEY; удалённым ИИ-клиентам нужен только MCP-токен.

HTTP-слушатель намеренно использует обычный HTTP. Пример не публикует свой порт; подключите контейнер Caddy, Nginx или Traefik к unraid-mcp-backend и проксируйте на http://unraid-mcp:3000. Для прокси, установленного на хосте, Docker 28 или новее может опубликовать 127.0.0.1:3000:3000; более старые версии Docker, включая некоторые релизы Unraid, могут предоставлять порты, опубликованные на localhost, той же сети уровня 2, поэтому вместо этого используйте частную сеть или явное правило брандмауэра. Не открывайте порт 3000 напрямую в интернет. Проверка работоспособности контейнера вызывает GET /health; трафик MCP использует /mcp.

Встроенное ограничение аутентификации идентифицирует непосредственного TCP-пира. За обратным прокси настройте ограничение скорости аутентификации также на прокси, поскольку все проксируемые клиенты могут использовать один адрес пира. Не передавайте непроверенное значение Host; либо сохраняйте внешнее имя хоста и включайте его в MCP_ALLOWED_HOSTS, либо переписывайте его на фиксированное разрешённое имя хоста.

Локальная конфигурация Docker-клиента

Конфигурация OpenCode, которая запускает образ через демон Docker:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "unraid": {
      "type": "local",
      "command": [
        "docker",
        "run",
        "--rm",
        "-i",
        "--env",
        "UNRAID_URL",
        "--env",
        "UNRAID_API_KEY",
        "unraid-mcp:0.1.1"
      ],
      "enabled": true,
      "environment": {
        "UNRAID_URL": "{env:UNRAID_URL}",
        "UNRAID_API_KEY": "{env:UNRAID_API_KEY}"
      }
    }
  }
}

Демон Docker, используемый ИИ-хостом, должен иметь доступ к образу. Перезапустите OpenCode после изменения его конфигурации.

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

Используйте либо UNRAID_CA_CERT, либо UNRAID_CA_CERT_PATH, но не оба. Предпочтительно доверять сертификату Unraid или локальному CA. UNRAID_TLS_SKIP_VERIFY=true — это явная крайняя мера, и она выводит предупреждение; она не изменяет поведение TLS глобально для других соединений Node.js.

Обычный HTTP поддерживается для изолированных устаревших сетей, но выводит предупреждение, поскольку ключ API и все данные сервера передаются без шифрования.

Настройка ИИ-клиента

OpenCode

Экспортируйте переменные окружения перед запуском OpenCode, затем добавьте этот локальный MCP в opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "unraid": {
      "type": "local",
      "command": ["node", "/absolute/path/to/unraid-mcp/dist/index.js"],
      "enabled": true,
      "environment": {
        "UNRAID_URL": "{env:UNRAID_URL}",
        "UNRAID_API_KEY": "{env:UNRAID_API_KEY}",
        "UNRAID_CA_CERT_PATH": "{env:UNRAID_CA_CERT_PATH}",
        "UNRAID_ALLOW_MUTATIONS": "{env:UNRAID_ALLOW_MUTATIONS}",
        "UNRAID_ALLOW_DESTRUCTIVE_MUTATIONS": "{env:UNRAID_ALLOW_DESTRUCTIVE_MUTATIONS}"
      }
    }
  }
}

Удалите необязательные записи окружения, которые не установлены. Перезапустите OpenCode после изменения его конфигурации.

Чтобы подключиться к постоянно работающему HTTP-контейнеру, экспортируйте его MCP-токен на машине с OpenCode и настройте удалённый сервер:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "unraid": {
      "type": "remote",
      "url": "https://mcp-server.example/mcp",
      "enabled": true,
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:MCP_AUTH_TOKEN}"
      }
    }
  }
}

Используйте URL HTTPS-обратного прокси, а не URL GraphQL Unraid. OpenCode отправляет MCP_AUTH_TOKEN в MCP; только MCP-контейнер отправляет UNRAID_API_KEY в Unraid.

Claude Code

Экспортируйте UNRAID_URL и UNRAID_API_KEY перед запуском Claude Code. Для области проекта создайте .mcp.json в проекте, где вы используете Claude Code:

{
  "mcpServers": {
    "unraid": {
      "command": "node",
      "args": ["/absolute/path/to/unraid-mcp/dist/index.js"],
      "env": {
        "UNRAID_URL": "${UNRAID_URL}",
        "UNRAID_API_KEY": "${UNRAID_API_KEY}"
      }
    }
  }
}

Claude Code разворачивает ссылки ${VAR} из своего окружения. Поэтому конфигурацию можно передавать без хранения ключа API. Добавляйте необязательные переменные в env только тогда, когда они установлены, например "UNRAID_ALLOW_MUTATIONS": "${UNRAID_ALLOW_MUTATIONS}".

Чтобы вместо этого запустить образ контейнера, используйте:

{
  "mcpServers": {
    "unraid": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env",
        "UNRAID_URL",
        "--env",
        "UNRAID_API_KEY",
        "unraid-mcp:0.1.1"
      ],
      "env": {
        "UNRAID_URL": "${UNRAID_URL}",
        "UNRAID_API_KEY": "${UNRAID_API_KEY}"
      }
    }
  }
}

Выполните claude mcp list, чтобы проверить сервер, затем используйте /mcp внутри Claude Code для проверки его статуса и инструментов. Claude Code запрашивает разрешение перед использованием сервера из .mcp.json с областью проекта. Используйте --scope user с командами MCP Claude Code, если вы предпочитаете частную конфигурацию между проектами в ~/.claude.json.

Для постоянно работающего HTTP-контейнера используйте вместо этого эту запись .mcp.json:

{
  "mcpServers": {
    "unraid": {
      "type": "http",
      "url": "https://mcp-server.example/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_AUTH_TOKEN}"
      }
    }
  }
}

Экспортируйте MCP_AUTH_TOKEN перед запуском Claude Code. Ссылка ${MCP_AUTH_TOKEN} разворачивается без сохранения её значения в конфигурации проекта.

Codex CLI и IDE

Codex CLI, расширение Codex IDE и настольное приложение ChatGPT используют общую конфигурацию MCP. Экспортируйте необходимые переменные, затем добавьте эту запись в ~/.codex/config.toml или в .codex/config.toml в доверенном проекте:

[mcp_servers.unraid]
command = "node"
args = ["/absolute/path/to/unraid-mcp/dist/index.js"]
env_vars = ["UNRAID_URL", "UNRAID_API_KEY"]
startup_timeout_sec = 10
tool_timeout_sec = 120
default_tools_approval_mode = "writes"

env_vars передаёт значения из окружения Codex без их записи в config.toml. Добавьте любые включённые необязательные настройки в этот список, например UNRAID_CA_CERT_PATH или UNRAID_ALLOW_MUTATIONS.

Чтобы вместо этого запустить образ контейнера, используйте:

[mcp_servers.unraid]
command = "docker"
args = [
  "run",
  "--rm",
  "-i",
  "--env",
  "UNRAID_URL",
  "--env",
  "UNRAID_API_KEY",
  "unraid-mcp:0.1.1",
]
env_vars = ["UNRAID_URL", "UNRAID_API_KEY"]
startup_timeout_sec = 10
tool_timeout_sec = 120
default_tools_approval_mode = "writes"

Режим одобрения writes запрашивает подтверждение для инструментов, которые не помечены как доступные только для чтения. Выполните codex mcp list, чтобы проверить сервер, и используйте /mcp в Codex TUI для просмотра подключенных инструментов. Перезапустите расширение IDE или настольное приложение ChatGPT после изменения общей конфигурации.

Для постоянно работающего HTTP-контейнера используйте вместо этого следующую запись:

[mcp_servers.unraid]
url = "https://mcp-server.example/mcp"
bearer_token_env_var = "MCP_AUTH_TOKEN"
startup_timeout_sec = 10
tool_timeout_sec = 120
default_tools_approval_mode = "writes"

Codex считывает bearer-токен из своего локального окружения и не сохраняет значение в config.toml.

Claude Desktop и другие stdio-хосты

Настройте хост для запуска:

node /absolute/path/to/unraid-mcp/dist/index.js

Обеспечьте наследование необходимых переменных окружения процессом хоста из ОС, менеджера служб или его менеджера секретов. Не помещайте ключ API в массив args. Если хост поддерживает значения окружения для каждого сервера, но не ссылки на секреты, учитывайте, что эти значения хранятся в файле конфигурации этого хоста.

MCP Inspector

После экспорта переменных вы можете интерактивно просматривать и вызывать инструменты:

pnpm dlx @modelcontextprotocol/inspector node dist/index.js

Inspector намеренно не является зависимостью проекта; используйте версию, одобренную для вашего окружения.

Инструменты

Следующие инструменты для чтения всегда зарегистрированы:

UNRAID_ALLOW_MUTATIONS=true добавляет:

UNRAID_ALLOW_DESTRUCTIVE_MUTATIONS=true дополнительно добавляет:

Он также позволяет unraid_control_parity_check запускаться с correct=true.

Аннотации MCP — это подсказки для клиентов, а не средства контроля доступа. Фактическими средствами контроля являются ограничения окружения и собственные разрешения ключа API Unraid.

Ограничения API

Текущая официальная схема не предоставляет всех действий WebGUI. В частности:

• Общие ресурсы доступны только для чтения; создание/редактирование общих ресурсов недоступно.

• Контейнеры Docker можно контролировать, обновлять и удалять, но нельзя создавать или редактировать.

• ВМ можно контролировать, но нельзя создавать, редактировать, клонировать, создавать снимки или удалять.

• Мутации завершения работы/перезагрузки хоста не опубликованы.

• Полные отчеты SMART и элементы управления самотестированием SMART не опубликованы.

• Docker restart был добавлен после API v4.35.1 и намеренно не используется этой целью совместимости.

• Типы ответов на мутации четности помечены Unraid как находящиеся в разработке.

См. docs/api-capabilities.md для официальных ссылок на источники и подробностей совместимости.

Разработка

pnpm typecheck
pnpm test
pnpm build
# Or run all three:
pnpm verify

Тесты используют локальные имитационные HTTP-серверы, а также клиенты MCP в памяти и Streamable HTTP. Для них не требуются Docker или работающий сервер Unraid.

Релизы контейнеров

GitHub Actions собирает контейнер и сканирует его на уязвимости для pull request'ов и изменений в main без использования учетных данных реестра. Публикация происходит только при выпуске семантически версионированного GitHub Release, такого как v0.1.1. Рабочий процесс релиза сканирует собранный образ перед доступом к DOCKERHUB_TOKEN защищенного окружения dockerhub, затем публикует теги версии, коммита и (для стабильных релизов) latest с атрибутами SBOM и происхождения.

Примечания по безопасности

• Stdio остается режимом по умолчанию и не открывает прослушивающий сетевой порт.

• Режим HTTP требует bearer-аутентификации. Отсутствующие токены генерируются с 256 битами криптографической случайности и намеренно записываются в журналы запуска.

• Сгенерированные токены являются операционными секретами: ограничьте доступ к журналам и настройте MCP_AUTH_TOKEN для стабильного развертывания.

• Режим HTTP проверяет заголовки Host и Origin, ограничивает частоту неудачных попыток аутентификации, ограничивает размер тел запросов и по умолчанию привязывается к loopback.

• Встроенный HTTP-прослушиватель не предоставляет TLS. Используйте HTTPS-обратный прокси и не открывайте его напрямую в интернет.

• Он никогда не записывает журналы приложения в stdout, который зарезервирован для MCP JSON-RPC.

• Он не принимает произвольные документы GraphQL от модели.

• Он не следует перенаправлениям и ограничивает размер ответа, количество строк журнала и продолжительность запроса.

• Отмена клиентом прерывает локальный HTTP-запрос; мутации, уже принятые Unraid, не могут быть отменены.

• Ошибки GraphQL редактируются, если они содержат настроенный ключ API.

• Серийные номера дисков, журналы, уведомления, сетевые адреса и другие данные сервера видны подключенному AI-клиенту. Ознакомьтесь с политикой обработки данных этого клиента.

Официальные ссылки

• Unraid API overview

• How to use the Unraid API

• Programmatic API key management

• Unraid API roadmap and version support

• API v4.35.1 generated GraphQL schema

• Unraid connection security guidance

• MCP TypeScript SDK stdio guidance

• MCP TypeScript SDK Streamable HTTP guidance

• Claude Code MCP configuration

• Codex MCP configuration

Лицензия

Этот проект лицензирован в соответствии с лицензией MIT.