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