Skip to main content
Glama
spranab

truenas-mcp

by spranab
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

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

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

Resources

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/spranab/truenas-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server