truenas-mcp

NASをAIアシスタントに組み込む場合、通常は操作ごとにMCPツールを1つ登録することになります。TrueNAS SCALEをきちんとカバーしようとすると、50〜80個のツールスキーマが必要になり、モデルが質問を1文字も読む前に、毎回のリクエストで約28,000トークンのコンテキストウィンドウを消費します。ストレージに触れるかどうかに関係なくです。

truenas-mcpは、TrueNAS SCALE REST API全体である18カテゴリにわたる278のアクションを、約200トークンしか消費しない1つの階層型ツールの背後でカバーします。モデルはどのカテゴリが存在するかを尋ね、必要なカテゴリにドリルダウンし、その後アクションを呼び出します。破壊的な操作は、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 UIから取得します：Settings > API Keys > Add

Related MCP server: Proxmox MCP Server

動作イメージ

あなた: 「プールは健全ですか？mediaデータセット用にNFS共有を作成できますか？」

→ 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" } })

モデルは、最初に truenas({ category: "sharing" }) を呼び出すことで nfs_share_create を発見しました。36個の共有アクションはプロンプトに含まれていません。

なぜ278個ではなく1つのツールなのか

完全な設定

# 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個の個別ツールを登録する代わりに（LLMのシステムプロンプトで約30kトークンを消費する）、このサーバーは**truenas という1つのツール**を3つの使用モードで公開します：

1. カテゴリを発見

truenas()

説明とアクション数を含む全18カテゴリを返します（約200トークン）。

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" })

「/mnt/tank/media 用にNFS共有を作成してください」

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

「システムアップデートを確認してください」

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

「sda でどのSMARTテストが実行されましたか？」

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

安全性

すべての破壊的操作には、パラメータに confirm: true が必要です：

• プールの作成/エクスポート/ディスク交換

• データセット/スナップショットの削除、スナップショットのロールバック

• VMの削除、アプリの削除/ロールバック

• システムの再起動/シャットダウン、アップデートの適用

• ディスクのワイプ、ブートディスクの接続/取り外し

• 証明書の削除、ブート環境の削除

• ディレクトリサービスの離脱、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