truenas-mcp
The most comprehensive MCP server for TrueNAS SCALE. 278 actions across 18 categories covering the entire TrueNAS REST API — behind a single hierarchical tool that won't bloat your LLM's context window.
Why This One?
| truenas-mcp | Others | |
|---|---|---|
| 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 |
Quick Start
# 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
License
MIT