4.0 KiB
truenas-mcp
MCP-сервер для управления TrueNAS через AI-ассистентов, завёрнутый через mcpo в OpenAPI-совместимый HTTP-сервис. Внутри используется пакет truenas-mcp-server (PyPI).
Официальный Go-бинарник truenas/truenas-mcp в Docker на TrueNAS SCALE не запустился (ошибка exec format error / ENOEXEC) - поэтому используется этот вариант на Python.
Важно: особенность сборки на TrueNAS SCALE + Dockge
Относительный build.context (например "." или "./truenas") в compose.yaml под Dockge на TrueNAS SCALE ненадёжен - Dockge и Docker-демон видят пути по-разному, из-за чего можно получить ошибку "unable to prepare context: path ... not found", даже если папка физически существует.
Поэтому build.context и volume в compose.yaml указывают абсолютным путём на отдельный датасет /mnt/ssd/apps/mcp/truenas, а не на папку самого стека Dockge.
Правильный порядок:
- В Dockge: "+ Compose" -> вставить compose.yaml из этого репозитория -> на вкладке Env добавить содержимое .env (см. .env.example) со своим реальным API-ключом TrueNAS -> Save (пока НЕ Deploy).
- Создать датасет /mnt/ssd/apps/mcp/truenas.
- Скопировать в этот датасет Dockerfile и config.json из этого репозитория.
- Только теперь нажать Deploy в Dockge.
Файлы
- compose.yaml - конфигурация сервиса (порт 8814:8000)
- Dockerfile - собирает образ на python:3.11-slim, ставит mcpo и truenas-mcp-server
- config.json - регистрирует truenas-mcp-server как stdio MCP-сервер для mcpo
- .env.example - шаблон; реальный .env с ключом никогда не коммитить
Переменные окружения
TRUENAS_API_KEY (в .env) - API-ключ TrueNAS TRUENAS_URL - URL TrueNAS, например http://192.168.31.100 TRUENAS_VERIFY_SSL - false для самоподписанного сертификата TRUENAS_ENABLE_DESTRUCTIVE_OPS - false блокирует разрушительные операции TRUENAS_LOG_LEVEL - уровень логирования, например INFO
Проверка после деплоя
docker logs truenas-mcp --tail 15
Должно быть: Successfully connected to: truenas / Uvicorn running on http://0.0.0.0:8000
Подключение клиентов
Важно: mcpo регистрирует сервер под именем "truenas" (из config.json) и монтирует его инструменты не в корне, а под этим префиксом. Корневой /openapi.json - это только служебный индекс mcpo со списком подключённых серверов (пустой "paths":{}), для подключения клиентов он не годится.
- Open WebUI: Admin Panel -> Settings -> External Tools -> Type: OpenAPI -> URL: http://truenas-ip:8814/truenas (без /openapi.json - Open WebUI сам добавляет этот суффикс при обращении к серверу).
- Прямая ссылка на саму схему (для curl / проверки в браузере): http://truenas-ip:8814/truenas/openapi.json
- Документация Swagger: http://truenas-ip:8814/truenas/docs
- Claude Desktop: сервис отдаёт OpenAPI, а не MCP Streamable HTTP - Custom Connectors не примет его напрямую. Для Claude Desktop используется локальный запуск того же truenas-mcp-server через uvx в claude_desktop_config.json.