truenas-mcp

Wiring a NAS into an AI assistant usually means registering one MCP tool per
operation. Cover TrueNAS SCALE properly and that is 50-80 tool schemas — around
28,000 tokens of your context window spent before the model has read a single
word of your question, on every request, whether or not you touch storage.

truenas-mcp covers 278 actions across 18 categories — the whole TrueNAS
SCALE REST API — behind one hierarchical tool that costs about 200 tokens.
The model asks what categories exist, drills into the one it needs, then calls
the action. Destructive operations refuse to run without confirm: true.

Install (60 seconds)

# 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

Get the API key from the TrueNAS UI: Settings > API Keys > Add.

What it looks like

You: "Are my pools healthy, and can you make an NFS share for the media
dataset?"

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

The model discovered nfs_share_create by calling truenas({ category: "sharing" }) first — it never had those 36 sharing actions in its prompt.

Why one tool instead of 278

Full configuration

# 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

Environment Variables

Claude Desktop Configuration

Add to your 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

How It Works — Hierarchical Tool Design

Instead of registering 278 individual tools (which would consume ~30k tokens in the LLM system prompt), this server exposes one tool called truenas with three usage modes:

1. Discover categories

truenas()

Returns all 18 categories with descriptions and action counts (~200 tokens).

2. Explore a category

truenas({ category: "storage" })

Returns all actions in that category with their required/optional parameters.

3. Execute an action

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

This means the LLM only pays the token cost for what it actually uses.

Categories

MCP Resources (12)

Read-only resources for dashboards — no tool call needed:

Example Conversations

"What pools do I have and are they healthy?"

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

"Create an NFS share for /mnt/tank/media"

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

"Check for system updates"

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

"What SMART tests have run on sda?"

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

Safety

All destructive operations require confirm: true in params:

• Pool create/export/disk replace
• Dataset/snapshot delete, snapshot rollback
• VM delete, app delete/rollback
• System reboot/shutdown, update apply
• Disk wipe, boot disk attach/detach
• Certificate delete, boot env delete
• Directory services leave, ACL set

Without confirm: true, these actions return an error message explaining what would happen.

API Compatibility

Built for TrueNAS SCALE REST API v2.0. Compatible with TrueNAS SCALE 22.x through 25.x.

Development

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

Related projects

Other MCP servers and agent infrastructure built by the same author:

• mcpier — self-hosted MCP control plane
  for your homelab; keeps API keys off your clients.
• saga-mcp — SQLite-backed project
  tracker so the agent doesn't lose the plan between sessions.
• yantrikdb-mcp — persistent
  cognitive memory for Claude Code, Cursor and Windsurf.
• swarmcode — real-time channel
  between Claude Code instances on different machines.
• brainstorm-mcp — multi-model
  debate as an MCP tool.

License

MIT