sr-truenas-mcp
staticrevolution-com/sr-truenas-mcp
Hardened MCP server for TrueNAS SCALE. 270 safety-tiered actions over WebSocket JSON-RPC, single hierarchical tool, fail-closed registration gate, layered response filtering. PolyForm Noncommercial.
Instalação
npx convez-ai staticrevolution-com/sr-truenas-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
sr-truenas-mcp
A hardened Model Context Protocol server for TrueNAS SCALE. 270 safety-tiered actions across 17 categories of TrueNAS surface, exposed through a single hierarchical MCP tool over WebSocket JSON-RPC 2.0.
Free for non-commercial use. Personal, hobbyist, educational, charitable, governmental, and research use is covered by the included PolyForm Noncommercial 1.0.0 license. Commercial use requires a separate paid license — contact
admin@staticrevolution.com.
Disclaimer
This software is provided as-is, with no warranty. By design it performs destructive operations on a TrueNAS system — deleting datasets, modifying shares, wiping disks, applying updates — and it does so on behalf of an LLM acting as a privileged operator. Warren Kelly and Static Revolution LLC accept no liability for data loss, downtime, or other damages resulting from its use. Read the safety-tier system in Architecture and test against a non-production TrueNAS before pointing it at anything you care about.
Why this exists
I built this to give Claude Code and OpenClaw (an n8n-driven agent framework) a way to actually manage my TrueNAS server — not just read status, but reorganize ZFS datasets, manage shares, configure replication, and the rest of the surface a NAS admin uses day to day. The two existing options at the time didn't fit:
- The upstream
spranab/truenas-mcpproject covered most of the API but ran on TrueNAS's REST API v2.0 (which doesn't appear in the current TrueNAS docs at all — the canonical transport is WebSocket JSON-RPC 2.0) and had no safety surface beyond per-handlerconfirm: truechecks. No tests. No CI. Two commits. Treating an LLM as a privileged operator on this kind of surface needed more than that. - The official
truenas/truenas-mcpfrom iXsystems is well built but intentionally narrow — 52 tools, with ZFS dataset management limited tocreate_datasetandquery_datasets. No delete, no update, no snapshot CRUD, no replication, no iSCSI, no certificates. Marked "Research Preview, not for production use." For my use case that wasn't workable.
So I forked spranab's project, migrated the transport to WebSocket, added a four-tier safety classification with centralized enforcement at the registry layer, added response filtering for sensitive fields, added path and dataset-name validation, and wrote a test suite. See COMPARISON.md for the full breakdown.
What it does
270 actions across 17 categories. The full surface (with safety tiers)
is documented at runtime via the truenas tool's discovery modes; the
short version:
| Category | Coverage |
|---|---|
| Storage | Pool create/destroy/import/export/replace/scrub. Dataset CRUD, snapshot CRUD, snapshot tasks, encryption (lock/unlock/key), quotas, permissions, promote |
| Sharing | SMB / NFS / iSCSI shares — full CRUD on shares, targets, extents, portals, initiators, target-extent mappings |
| Filesystem | stat, listdir, mkdir, chown, set-permissions (POSIX), set-ACL (NFSv4), get-ACL |
| System | Service start/stop/restart/control, system.info, system_general config, NTP, mail, API keys, boot environments |
| Network | Interface CRUD, static routes, network configuration, commit/rollback staged changes |
| Account | User CRUD, group CRUD, privilege CRUD, set-password |
| Apps | Install / start / stop / upgrade / delete, app catalog, Docker config |
| VMs | VM CRUD, device CRUD, start/stop/restart |
| Replication | Replication tasks, cloud sync, cloud backup, rsync tasks |
| Data protection | Periodic snapshot tasks |
| Disks | Query, wipe, SMART results (initiation not exposed via WS API) |
| Certificates | Certificate CRUD, ACME, DNS authenticators |
| Directory services | Status, configure, leave, refresh cache |
| Reporting | System / network / disk / ARC metrics |
| Update | Check, download, apply system updates |
| Alerts | Query, dismiss, restore alerts; alert-service CRUD |
| Audit | Query audit logs |
Compare against docs/full-features.md in truenas/truenas-mcp
for the official Research Preview's narrower surface.
What makes it different
Three things, in roughly the order they matter:
Single hierarchical tool. The MCP server registers one tool — truenas —
not 270. The model spends prompt budget on one tool definition (~200
tokens) instead of 270 separate JSON Schemas. Action discovery is a
runtime call (truenas({ mode: "list_categories" }) →
truenas({ category: "storage" }) → truenas({ category: "storage", action: "dataset_create", ... })). For a session that uses ten different
TrueNAS actions, the prompt cost is roughly the same as one. This is
inherited from spranab's design and is the single biggest reason
hierarchical works as a pattern at this surface size.
Centralized safety at the registry layer, not per-handler. Every
action has a tier in src/safety.ts — a pure data file. The registry
checks the tier before dispatching to the handler. Tier 0 actions never
register, so they're not even discoverable. Tier 1 requires confirm: true AND a reason string. Tier 2 requires confirm: true. Tier 3 is
open. New actions ship unable to register if they're not in the tier
map — which is the property I wanted: a contributor cannot add an
action without making a classification decision.
Centralized response filtering. Every handler return value passes
through filterSensitiveFields in src/filters.ts before reaching the
MCP transport. Three layers: 57 exact key matches (password,
privatekey, unixhash, salt, …), 9 suffix patterns (_password$,
_token$, _secret$, …), and a 15-entry allowlist that protects
benign *_key identifiers (id_key, pool_key, vdev_key),
password-policy descriptors, and public-key material. The allowlist
matters — without it, suffix matching would redact things like
pool_key (a TrueNAS internal identifier) and break legitimate reads.
Everything else — path validation, dataset-name validation, schema tightening on high-risk methods, structured logging, the standalone binary build, CI — falls out of those three decisions.
Quick install
The fastest path:
# Download the binary from the latest release
curl -L https://github.com/staticrevolution-com/sr-truenas-mcp/releases/latest/download/sr-truenas-mcp-linux-x64.tar.gz | tar xz
chmod +x sr-truenas-mcp
# Verify
./sr-truenas-mcp --version
# Run
TRUENAS_URL=wss://truenas.local:444 \
TRUENAS_API_KEY=$(cat ~/.truenas-key) \
TRUENAS_VERIFY_SSL=false \
./sr-truenas-mcp
Linux x64 only for the binary distribution. Other platforms run from
source via npm install && npm run build && node dist/cli.js.
For Docker, Claude Code / Claude Desktop / VS Code MCP integration,
see docs/INSTALL.md.
Configuration
Three required environment variables:
| Variable | Example | Notes |
|---|---|---|
TRUENAS_URL | wss://truenas.local:444 | Must be wss://. The TrueNAS middleware revokes API keys used over ws:// |
TRUENAS_API_KEY | 1-... | Generated in TrueNAS UI: User → API Keys → Add. Key needs admin scope for the actions you intend to run |
TRUENAS_VERIFY_SSL | false | Set false for self-signed certs (most home installs); leave unset/true for properly issued certs |
Optional: TRUENAS_LOG_LEVEL, TRUENAS_KEEPALIVE_INTERVAL_MS,
TRUENAS_SKIP_PREFLIGHT. Full reference at
docs/CONFIGURATION.md.
Architecture
The server is a single MCP tool exposed over stdio, backed by a WebSocket JSON-RPC 2.0 client to TrueNAS's middleware. The registry between them enforces safety, schema validation, and response filtering.
┌────────────────────────────────────────┐
LLM client ───► │ MCP tool: truenas │
(stdio/SSE) │ │
│ modes: │
│ "list_categories" → 17 categories │
│ "list_actions" → tier-tagged │
│ "execute" → handler │
└─────────────┬──────────────────────────┘
│
┌─────────────▼──────────────────────────┐
│ ToolRegistry (src/registry.ts) │
│ 1. Tier check (0=blocked, │
│ 1=confirm+reason, │
│ 2=confirm, │
│ 3=open) │
│ 2. Zod schema validation │
│ 3. Handler dispatch │
│ 4. filterSensitiveFields() │
└─────────────┬──────────────────────────┘
│
┌─────────────▼──────────────────────────┐
│ TrueNASClient (src/client.ts) │
│ WebSocket DDP / JSON-RPC 2.0 │
│ request multiplexing, reconnect, │
│ job polling with exponential backoff │
└─────────────┬──────────────────────────┘
│
▼
wss://truenas/websocket
Why WebSocket and not REST
Modern TrueNAS docs are 100% WebSocket JSON-RPC 2.0 — the REST API v2.0
that spranab's project used isn't documented in the current TrueNAS
manual. The official truenas/truenas-mcp from iXsystems is also
WebSocket-only and explicitly refuses unencrypted ws://. That's the
direction signal. REST will work for some time but is on borrowed time.
The migration also eliminated a class of bugs: REST passed dataset and pool IDs as URL path segments, which require URL-encoding. WebSocket passes them as method parameters. The encoding-bug class disappeared entirely on the transport switch.
Why a 4-tier safety classification
A binary "destructive: yes/no" gate doesn't fit TrueNAS's surface.
service_stop is recoverable; disk_wipe is not. dataset_delete
needs an explicit human reason because mistakes are not recoverable
within the session. Most reads need no gate at all. The four tiers
map cleanly:
- Tier 0 — never register. 8 actions: reboot, shutdown, the raw-API escape hatch, cron and init/shutdown script creation. These cannot be made safe within an MCP session and the only correct answer is "do this through TrueNAS directly."
- Tier 1 — confirm + reason. 20 actions.
pool_export,disk_wipe,dataset_delete,snapshot_rollback,update_apply,bootenv_activate,system_config_download(returns secret seed + encryption keys),network_commit_changes(could lock you out of the box). Two-call confirmation: first call returns a structured warning describing exactly what's about to happen; second call withconfirm: trueand areasonstring actually runs it. - Tier 2 — confirm. 81 actions. Service stop/restart, snapshot delete, share create/delete, user/group CRUD, certificate CRUD, cloud sync delete, etc. Recoverable but should not happen by accident.
- Tier 3 — open. 169 actions. All reads, all queries, safe creates
(e.g. read-only
query_filtersoperations).
The data lives in src/safety.ts and is enforced at registration. An
action with no tier assignment fails to register; the test suite
verifies the tier map matches the registered set on every CI run.
Why centralized enforcement, not per-handler
Spranab's design puts if (!confirm) return error checks inside each
handler that wants confirmation. That works until someone adds a new
handler and forgets the check. There's no compile-time or test-time
signal that something was missed.
The registry approach is fail-closed: a new action ships in the
codebase, but if it's not in ACTION_TIERS, it doesn't register, and
the test suite (safety-completeness.test.ts) flags the missing
classification as a CI failure. The 32 in-handler confirm checks
that survived from upstream remain as defense in depth, but they are
not the primary gate.
Why the API escape hatch was removed
Spranab's upstream had a truenas_api_call action that let the LLM
call any TrueNAS REST endpoint with arbitrary parameters. With that
present, every other safety gate becomes cosmetic — the LLM can route
around them by going to the raw API. Removed entirely; not even a
tier 0 entry. If you need to call a method this server doesn't expose,
add it deliberately and classify it.
Why response filtering is post-call, not pre-call
The redaction is about what reaches the LLM context, not what reaches
TrueNAS. A pre-call filter would need to know every method's
parameter shape; a post-call filter only needs to know field names,
which is a much smaller surface. The filter is recursive (handles
nested objects and arrays), and the layered matcher (exact + suffix +
allowlist) emerged because exact-only matching missed flat names like
certificate_private_key, while pure suffix matching over-redacted
benign identifiers like pool_key.
For full architecture detail, see docs/ARCHITECTURE.md.
Security posture
The threat model assumes the LLM operator is not malicious but is a privileged operator who will execute whatever the model decides to execute, and the model is fallible. Guardrails are sized to that assumption, not to "the model is adversarial" (which is a different and much harder problem).
Concretely:
- Destructive actions are gated at the registry layer — see safety tiers above. The two-call confirmation flow forces an explicit acknowledgment from the calling agent before tier 1 or tier 2 actions execute.
- Path validation runs at the handler boundary on every
filesystem-touching action (23 sites): paths must start with
/mnt/, no..traversal, no null bytes. ZFS dataset names go through a separate validator (3 sites): a restricted character set, no.., no null bytes, max length 255. - Schema validation wraps every handler. Zod schemas reject
malformed parameters before any TrueNAS call is made. High-risk
methods (
pool.create,system.general.update,replication.create,vm.create,interface.create,disk.wipe) have tightened enums and patterns instead of permissiveRecord<string, unknown>. - Response filtering strips passwords, private keys, tokens,
recovery codes, salts, and similar fields from every handler return
before it reaches the LLM. The allowlist preserves public-key
material (which is access-control-relevant but not secret) so
user.queryreads still surface SSH public keys. - Per-connection TLS settings. No
process.env.NODE_TLS_REJECT_UNAUTHORIZEDmutation. TheverifySslflag is a per-connection option on the WebSocket library, scoped to this server's connections only. - No raw-API escape hatch. Removed from the upstream surface.
For full threat model, supported versions, and vulnerability disclosure
process, see SECURITY.md.
Comparison to alternatives
Short version (full detail in COMPARISON.md):
| sr-truenas-mcp | spranab/truenas-mcp | truenas/truenas-mcp | |
|---|---|---|---|
| Transport | WebSocket | REST | WebSocket |
| Action coverage | 270 (17 categories) | ~278 (18 categories) | 52 flat tools |
| ZFS dataset ops | Full CRUD + snapshots | Full CRUD + snapshots | create_dataset and query_datasets only |
| Safety model | 4-tier, centralized | Per-handler confirm | Dry-run preview |
| Response filtering | Centralized 3-layer | None | Per-handler hand-crafted masking |
| Tests / CI | 226 / yes | 0 / no | 27 / yes |
| License | PolyForm-NC 1.0.0 | MIT | GPL-3.0 |
| Status | v1.1.1 | Single-shot publication (2 commits) | "Research Preview" |
Each project optimizes for different things. The official version has
better wizard-style UX and ships cross-platform binaries (macOS / Windows
/ Linux); sr-truenas-mcp ships Linux-only and trades that for breadth +
safety surface. If create_dataset is all you need, the official one is
the right choice.
Development approach
Requirements I set, and the patterns that satisfied them
Two kinds of decisions shaped this codebase: requirements I brought to the project as a sysadmin, and the specific architectural patterns that satisfied those requirements. The distinction matters because the patterns were developed collaboratively with AI tooling (Claude Code); the requirements are mine and predate the implementation.
Strategic: fork rather than upstream contribution. Spranab's repo is two commits on a single day in March 2026, no tests, no CI, no ongoing maintenance. The changes the project needed (transport rewrite, safety classification, validation, response filtering, test suite) were too large to land as a series of PRs into a project with no review process. A fork preserves the inherited architecture (which is good) while letting the safety surface evolve at the pace of an active development cycle.
Strategic: WebSocket transport over REST. REST API v2.0 isn't in
the current TrueNAS docs; the iXsystems-published MCP server is
wss-only with active rejection of unencrypted ws://. That's the
direction signal; staying on REST would have been swimming against
it. The migration also eliminated a whole class of URL-encoding bugs.
Requirement: destructive actions must be classified by remediation
cost, not by a binary destructive/non-destructive flag. service_stop
(recoverable in 30 seconds) and disk_wipe (no recovery) should not
trigger the same confirmation. Most reads need no gate at all. The
four-tier scheme (src/safety.ts) that satisfies this requirement
was developed collaboratively — three or five tiers were also viable;
four was the resolution.
Requirement: the safety gate must fail closed. A new action
shipping without a classification must not silently become callable.
Per-handler if (!confirm) checks (the upstream pattern) don't have
this property — a handler can be added without the check and nothing
catches it. The registry-layer enforcement pattern that satisfies
this — gate sits at registration, unclassified actions throw,
safety-completeness test asserts no drift on every CI run — was
developed collaboratively. Middleware, decorator, and
configuration-driven approaches were also considered.
Requirement: no escape hatch the LLM can route around. The
upstream truenas_api_call action let the model call any TrueNAS
endpoint with arbitrary params. With it present, every other safety
gate becomes cosmetic. Non-negotiable: it had to be removed
entirely — not gated, not env-flagged, not even a tier 0 entry. The
implementation is straightforward (delete the action and its
namespace); the requirement is the load-bearing piece.
Requirement: secrets must not reach the LLM context, and the
filter must not over-redact benign identifiers. Pre-call parameter
filtering doesn't address response-side leakage, which is the
dominant concern. Per-handler hand-crafted masking (the iXsystems
approach) has the same fail-closed problem as per-handler
confirm — a new handler ships with no masking. The
post-call layered matcher (exact keys + suffix patterns +
NEVER_REDACT allowlist) in src/filters.ts was the pattern that
emerged from collaboration. The layering specifically resolves two
real bugs: pure exact matching missed certificate_private_key (and
similar flat names), and pure suffix matching like _key$
over-redacted benign identifiers like pool_key, id_key,
vdev_key. The allowlist won't be obvious until you hit the
over-redaction; it took an audit pass to discover.
Things that came out of the audit pass
A few specific issues caught during a pre-release audit, illustrative of the kind of bugs that ship in MCP servers when nobody is looking. The bugs were found and fixed during the collaborative implementation work, not by line-by-line code review on my part:
- Late-response race in the WebSocket client. A request times out;
the caller's promise rejects via the timer. Then the server response
arrives. The message handler called
resolve()on a settled promise, which produced an unhandled rejection. Fixed by adding asettledflag on each pending request and routing both timer and message paths through a singlesettlePending()state-transition function. - Send-error orphan.
ws.sendruns the error callback async; the pending Map entry was being added after the send call, so an immediate send error fired the callback before the pending entry existed. Fixed by adding to the Map first, sending second, withtry/catcharound synchronous send errors. - Reconnect dropped idempotent callers needlessly. Original
reconnect logic rejected every in-flight request on disconnect. Read
methods (
*.query,*.get_instance,*.config,core.get_jobs) are idempotent and could safely retry post-reconnect; only writes needed to fail. Now that's an explicit policy with a typedReconnectAbortederror for the non-retryable cases. system.general.updateschema wasRecord<string, unknown>. Strict object schema with.strict()rejects unknown keys. TrueNAS occasionally adds undocumented fields between releases; better to fail visibly and update the schema than to silently accept.- Filter audit found 12+ missing sensitive field names that
upstream had been quietly leaking —
auth_token,reconnect_token,host_key,bind_password,recovery_codes, plus the suffix matcher catch-all for the*_private_keyfamily.
Doc-source-of-truth gate
src/__tests__/doc-sync.test.ts reads the numerical claims in the
project's CLAUDE.md (filter pattern counts, per-tier action counts,
validate-call-site counts) and asserts they match what's actually in
the source. CI fails if anyone edits src/filters.ts without updating
the docs. npm run audit:counts produces the same numbers manually
when developing. The requirement was "stale documentation is one of
the most common failure modes in homelab tooling and I want a forcing
function rather than discipline"; the specific test-driven
implementation of that forcing function was developed collaboratively.
How the work was actually done
Project requirements and safety non-negotiables — destructive actions must be classified and gated, the system must fail closed, no escape hatches that route around the gates, secrets must not reach the LLM context — were set by me from a sysadmin's perspective. The specific architectural patterns that satisfy those requirements (the four-tier classification, registry-layer enforcement, post-call layered response filter) were developed collaboratively with AI tooling (Claude Code). Code was reviewed at the architectural and behavioral level rather than line-by-line; the test suite (211 tests across 12 files), the fail-closed registration gate, and the doc-sync CI gate exist partly to compensate for that review model. Architectural and behavioral correctness has been verified; mechanical line-level review of every diff has not, and that's a deliberate trade-off — the project shipped in 16 days instead of six months.
The outcome of this trade-off is auditable: the test suite is in
src/__tests__/, the safety classification is a pure data file at
src/safety.ts, the response filter is a 169-line pure function at
src/filters.ts, and the CI gates are in .github/workflows/. None
of those are hidden behind abstractions; a reviewer who wants to
verify any architectural claim in this README can do so against the
source in minutes.
Contributing
Issues and bug reports welcome via GitHub Issues. For feature work, please open an issue first to discuss scope before sending a PR — the action surface and safety classifications are opinionated and I want to make sure proposed changes fit.
Contributors agree to license their contributions under the project's
PolyForm Noncommercial 1.0.0 license. By submitting a PR you confirm
you have the right to do so. See CONTRIBUTING.md
for details.
License
PolyForm Noncommercial 1.0.0 — a source-available license that permits free use for personal, hobbyist, educational, charitable, governmental, and research purposes. It is not OSI-approved open source; that is intentional.
Commercial use — including use in for-profit business operations, in a commercial product or service, or use that produces revenue — requires a separate paid commercial license. Email admin@staticrevolution.com.
NOTICES preserves the upstream MIT attribution from
spranab/truenas-mcp, which is
required for distributions of this project.
About the author
Warren Kelly / Static Revolution — senior systems administrator with a background in MDM, SSO, IAM, infrastructure, and automation. This project came out of needing a tool good enough to let agents I trust manage a NAS I rely on, and not finding one that fit.
GitHub: whasamatau ·
Email: admin@staticrevolution.com
Acknowledgments
Forked from spranab/truenas-mcp. Hardening, the WebSocket JSON-RPC migration, and ongoing development was done with assistance from Anthropic's Claude.