truenas-mcp

Подключение NAS к ИИ-ассистенту обычно означает регистрацию одного MCP-инструмента на каждую операцию. Чтобы полноценно покрыть TrueNAS SCALE, потребуется 50–80 схем инструментов — около 28 000 токенов вашего контекстного окна тратится до того, как модель прочитает хоть одно слово вашего вопроса, при каждом запросе, независимо от того, касаетесь ли вы хранилища.

truenas-mcp покрывает 278 действий в 18 категориях — весь REST API TrueNAS SCALE — с помощью одного иерархического инструмента, который стоит около 200 токенов. Модель спрашивает, какие категории существуют, углубляется в нужную, а затем вызывает действие. Деструктивные операции отказываются выполняться без confirm: true.

Установка (60 секунд)

# No install needed
TRUENAS_URL=https://truenas.local TRUENAS_API_KEY=1-abc123 npx truenas-mcp

Claude Code:

claude mcp add truenas -- npx -y truenas-mcp   --env TRUENAS_URL=https://truenas.local   --env TRUENAS_API_KEY=1-your-api-key-here

Получите API-ключ в интерфейсе TrueNAS: Settings > API Keys > Add.

Related MCP server: Proxmox MCP Server

Как это выглядит

Вы: «Здоровы ли мои пулы, и можете ли вы создать NFS-шару для датасета media?»

→ truenas({ category: "storage", action: "pool_list" })
  tank — ONLINE, 68% used, 0 errors

→ truenas({ category: "sharing", action: "nfs_share_create",
            params: { path: "/mnt/tank/media", comment: "Media share" } })

Модель обнаружила nfs_share_create, сначала вызвав truenas({ category: "sharing" }) — в её промпте никогда не было этих 36 действий для шаринга.

Почему один инструмент вместо 278

Полная конфигурация

# Using npx (no install needed)
TRUENAS_URL=https://truenas.local TRUENAS_API_KEY=1-abc123 npx truenas-mcp

# Or install globally
npm install -g truenas-mcp

Переменные окружения

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

Добавьте в ваш claude_desktop_config.json:

{
  "mcpServers": {
    "truenas": {
      "command": "npx",
      "args": ["-y", "truenas-mcp"],
      "env": {
        "TRUENAS_URL": "https://truenas.local",
        "TRUENAS_API_KEY": "1-your-api-key-here",
        "TRUENAS_VERIFY_SSL": "false"
      }
    }
  }
}

Claude Code

claude mcp add truenas -- npx -y truenas-mcp \
  --env TRUENAS_URL=https://truenas.local \
  --env TRUENAS_API_KEY=1-your-api-key-here \
  --env TRUENAS_VERIFY_SSL=false

Как это работает — иерархический дизайн инструмента

Вместо регистрации 278 отдельных инструментов (что потребовало бы ~30 тыс. токенов в системном промпте LLM), этот сервер предоставляет один инструмент под названием truenas с тремя режимами использования:

1. Обнаружение категорий

truenas()

2. Изучение категории

truenas({ category: "storage" })

3. Выполнение действия

truenas({ category: "storage", action: "pool_list" })
truenas({ category: "storage", action: "dataset_create", params: { name: "tank/media", compression: "LZ4" } })

Это означает, что LLM платит за токены только за то, что действительно использует.

Категории

MCP-ресурсы (12)

Ресурсы только для чтения для панелей — вызов инструмента не требуется:

Примеры диалогов

«Какие у меня пулы и здоровы ли они?»

→ truenas({ category: "storage", action: "pool_list" })

«Создайте NFS-шару для /mnt/tank/media»

→ truenas({ category: "sharing", action: "nfs_share_create", params: { path: "/mnt/tank/media", comment: "Media share" } })

«Проверьте наличие обновлений системы»

→ truenas({ category: "update", action: "update_check" })

«Какие SMART-тесты выполнялись на sda?»

→ truenas({ category: "disk", action: "disk_smart_test_list", params: { disk: "sda" } })

Безопасность

Все деструктивные операции требуют confirm: true в параметрах:

• Создание/экспорт пула, замена диска

• Удаление датасета/снапшота, откат снапшота

• Удаление ВМ, удаление/откат приложения

• Перезагрузка/выключение системы, применение обновления

• Стирание диска, подключение/отключение загрузочного диска

• Удаление сертификата, удаление загрузочного окружения

• Выход из служб каталогов, установка ACL

Без confirm: true эти действия возвращают сообщение об ошибке с объяснением, что произойдёт.

Совместимость с API

Создано для TrueNAS SCALE REST API v2.0. Совместимо с TrueNAS SCALE 22.x–25.x.

Разработка

git clone https://github.com/spranab/truenas-mcp
cd truenas-mcp
npm install
npm run build
npm run dev  # watch mode

Связанные проекты

Другие MCP-серверы и агентская инфраструктура того же автора:

• mcpier — самохостинговая управляющая плоскость MCP для вашего домашнего сервера; не хранит API-ключи на ваших клиентах.

• saga-mcp — трекер проектов на SQLite, чтобы агент не терял план между сессиями.

• yantrikdb-mcp — постоянная когнитивная память для Claude Code, Cursor и Windsurf.

• swarmcode — канал реального времени между экземплярами Claude Code на разных машинах.

• brainstorm-mcp — многомодельное обсуждение как MCP-инструмент.

Лицензия

MIT