nasbridge — control TrueNAS from Claude

License: MIT TypeScript

An MCP server for TrueNAS that lets Claude Desktop, Claude Code, Cursor or anyother MCP client manage your NAS — ZFS pools and datasets, SMB and NFS shares,snapshots, replication, VMs, alerts and network config. 278 actions in all.

Ask for "a dataset on tank with lz4 and a daily snapshot task", or "which poolsare degraded", and it happens over the wire rather than through the web UI.

TrueNAS 26 drops the REST API in favour of JSON-RPC 2.0 over WebSocket, so thisserver speaks that transport directly.

One tool, not 278

The design decision worth stealing: this exposes a single hierarchicaltruenas tool rather than one tool per action.

Most MCP servers register a flat tool per operation. At 278 actions that consumesa large share of the context window before the model has done any work, anddegrades tool selection as the list grows. Here the model discovers categories,lists the actions in one, then executes with parameters — three cheap round tripsinstead of a permanently expensive tool manifest.

How it works

This started as a fork of the truenas-mcp package, which targets the REST APIthat TrueNAS 26 removed. The tool handlers are largely unchanged — they still calla REST-style client (client.get/post/put/delete). What was rewritten iseverything beneath: a path-translator maps each REST path to its JSON-RPC method(GET /pool becomes pool.query, PUT /pool/id/1 becomes pool.update), and aws client sends those calls over a single authenticated WebSocket connection.

Keeping the REST-shaped seam meant the 278 handlers did not have to be rewrittento change transport.

Authentication is auth.login_with_api_key on connect. The connection keeps itself alive with a 30s core.ping. Long-running operations are tracked via core.get_jobs.

Tools

The truenas tool takes category, action and params:

No args or category="help" — list all categories with action counts
category only — list the actions in that category and their parameters
category + action + params — execute

278 actions are wired across these categories:

Category	Covers
`system`	System info, services, mail, API keys, power, NTP
`storage`	Pools, datasets, snapshots, periodic snapshot tasks
`sharing`	SMB, NFS and iSCSI (targets, extents, portals, initiators)
`network`	Interfaces, global config, static routes, staged changes
`vm`	Virtual machines and VM devices
`alert`	System alerts and alert notification services
`data_protection`	Replication, cloud sync/backup, cron, rsync, SSH credentials
`filesystem`	stat, listdir, mkdir, permissions, ACLs, ownership

Destructive actions (reboot, shutdown and similar) require an explicit confirm: true parameter.

Resources

Read-only resources surface common state without a tool call: truenas://system/info, truenas://storage/pools, truenas://storage/datasets, truenas://services, truenas://alerts, truenas://network/summary, truenas://sharing, truenas://vms, truenas://apps, truenas://disks, truenas://boot/environments and truenas://system/update.

Configuration

Variable	Required	Default	Notes
`TRUENAS_URL`	yes	—	TrueNAS host or URL. `http://`/`https://` is rewritten to `wss://`; `/api/current` is appended if absent
`TRUENAS_API_KEY`	yes	—	Generate in TrueNAS: Credentials → API Keys → Add
`TRUENAS_VERIFY_SSL`	no	`true`	Set `false` to skip TLS verification (self-signed certs)

The client connects with wss:// by default. A self-signed cert needs TRUENAS_VERIFY_SSL=false.

Don't pass a ws:// URL. http:// and https:// are rewritten to wss://, but anexplicit ws:// is left alone — and TrueNAS auto-revokes any API key it sees used overan insecure transport. You get an authentication failure that looks like a bad key, andthe key really is dead. Regenerate it and connect over wss://.

Requirements

TrueNAS 26 or later (earlier versions expose a different WebSocket shape)
Node.js 18+ (CI proves the built server imports on 18 and 22)
A TrueNAS API key — Credentials → API Keys → Add
An MCP client: Claude Desktop, Claude Code, Cursor, or anything else speaking MCP

Install and run

git clone https://github.com/maverick0628/nasbridge.git
cd nasbridge
npm install
npm run build
TRUENAS_URL=https://truenas.local TRUENAS_API_KEY=1-yourkey node dist/cli.js

Create the API key in the TrueNAS UI under Credentials → Local Users → API Keys.Keep it in your MCP client config or a local .env, never in the repo — .env isgitignored for that reason.

The server speaks MCP over stdio. Add it to your MCP client config — for ClaudeDesktop that is claude_desktop_config.json, for Claude Code .mcp.json:

{
  "command": "node",
  "args": ["/path/to/nasbridge/dist/cli.js"],
  "env": {
    "TRUENAS_URL": "https://truenas.local",
    "TRUENAS_API_KEY": "1-yourkey",
    "TRUENAS_VERIFY_SSL": "false"
  }
}

Tests

npm test

Unit tests cover the REST-to-WebSocket path translator and the client against a mock WebSocket server. test/e2e-live.mjs runs the dataset create/get flow against a real TrueNAS instance.

Notes

TrueNAS 26 tightened dataset validation: atime, compression and sync must be uppercase string literals (ON, OFF, LZ4, STANDARD). The storage tools normalise these before create/update, so the model can pass natural values.

Built against TrueNAS 26. Earlier versions expose a different WebSocket API shape and are not supported.

License

MIT — see LICENSE.

nasbridge — control TrueNAS from Claude