Truenas Mcp

truenas-mcp

[](https://www.npmjs.com/package/truenas-mcp) [](https://www.npmjs.com/package/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

| | truenas-mcp | Typical NAS MCP server | |---|---|---| | Actions | 278 | 5-80 | | Token footprint | ~200 tokens (1 tool) | 5,000-30,000 tokens (50-80 tools) | | Discovery | Hierarchical — ask for what you need | Flat — everything loaded upfront | | MCP Resources | 12 read-only dashboards | 0 | | Install | npx truenas-mcp | Build from source / pip | | Safety | Destructive ops require confirm: true | Varies |

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

| Variable | Required | Description | |----------|----------|-------------| | TRUENAS_URL | Yes | TrueNAS instance URL (e.g. https://truenas.local) | | TRUENAS_API_KEY | Yes | API key from TrueNAS UI: Settings > API Keys > Add | | TRUENAS_VERIFY_SSL | No | Set to false to skip SSL verification (self-signed certs) |

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

| Category | Actions | Covers | |----------|---------|--------| | system | 24 | System info, config, services, mail, API keys, NTP | | storage | 32 | Pools, datasets, snapshots, periodic snapshot tasks | | sharing | 36 | SMB/CIFS, NFS exports, iSCSI targets/extents/portals/initiators | | network | 15 | Interfaces, global config, static routes, IPMI, staged changes | | account | 16 | Users, groups, privileges/roles | | disk | 7 | Physical disks, SMART tests, temperatures | | vm | 16 | Virtual machines, VM devices (disk, NIC, display, PCI) | | app | 17 | Docker apps, container runtime config | | update | 14 | System updates, boot environments, boot pool | | certificate | 8 | TLS certs, ACME/Let's Encrypt, DNS authenticators | | alert | 10 | Alerts, notification services (Slack, email, PagerDuty) | | data_protection | 49 | Replication, cloud sync, cloud backup, cron, rsync, init scripts, SSH keys | | filesystem | 7 | stat, listdir, mkdir, permissions, ACLs, chown | | reporting | 3 | Metrics config, graphs, time-series data | | directory | 8 | Active Directory, LDAP, Kerberos | | service_config | 12 | SSH, FTP, SNMP, UPS, system tunables | | audit | 3 | Audit logs, audit configuration | | api | 1 | Raw API escape hatch for any endpoint |

MCP Resources (12)

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

| Resource | URI | Description | |----------|-----|-------------| | System Info | truenas://system/info | Version, hostname, uptime, hardware | | Pools | truenas://storage/pools | All pools with capacity and health | | Datasets | truenas://storage/datasets | All datasets with properties | | Services | truenas://services | Service status overview | | Alerts | truenas://alerts | Current system alerts | | Network | truenas://network/summary | Interfaces, IPs, DNS, gateway | | Shares | truenas://sharing | All SMB, NFS, and iSCSI shares | | VMs | truenas://vms | Virtual machines with status | | Apps | truenas://apps | Installed applications | | Disks | truenas://disks | Physical disks info | | Boot Envs | truenas://boot/environments | Boot environments | | Update | truenas://system/update | Update configuration |

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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: spranab
• Source: spranab/truenas-mcp
• License: MIT
• Homepage: https://www.npmjs.com/package/truenas-mcp

Install and usage instructions live in the source repository linked above.