convez.ai
MCP Server
staticrevolution-com

sr-truenas-mcp

staticrevolution-com/sr-truenas-mcp

Ver no GitHub
BomPluginScore · de 0 a 100

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-mcp

1 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

Estrelas
3
Forks
0
Acompanhando
0
Saúde
75%
Último commit
há 1 dia
Versão
v1.4.3
Issues abertas
10
Contribuidores
2

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.

CI Latest release License: PolyForm-NC 1.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-mcp project 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-handler confirm: true checks. 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-mcp from iXsystems is well built but intentionally narrow — 52 tools, with ZFS dataset management limited to create_dataset and query_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:

CategoryCoverage
StoragePool create/destroy/import/export/replace/scrub. Dataset CRUD, snapshot CRUD, snapshot tasks, encryption (lock/unlock/key), quotas, permissions, promote
SharingSMB / NFS / iSCSI shares — full CRUD on shares, targets, extents, portals, initiators, target-extent mappings
Filesystemstat, listdir, mkdir, chown, set-permissions (POSIX), set-ACL (NFSv4), get-ACL
SystemService start/stop/restart/control, system.info, system_general config, NTP, mail, API keys, boot environments
NetworkInterface CRUD, static routes, network configuration, commit/rollback staged changes
AccountUser CRUD, group CRUD, privilege CRUD, set-password
AppsInstall / start / stop / upgrade / delete, app catalog, Docker config
VMsVM CRUD, device CRUD, start/stop/restart
ReplicationReplication tasks, cloud sync, cloud backup, rsync tasks
Data protectionPeriodic snapshot tasks
DisksQuery, wipe, SMART results (initiation not exposed via WS API)
CertificatesCertificate CRUD, ACME, DNS authenticators
Directory servicesStatus, configure, leave, refresh cache
ReportingSystem / network / disk / ARC metrics
UpdateCheck, download, apply system updates
AlertsQuery, dismiss, restore alerts; alert-service CRUD
AuditQuery 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:

VariableExampleNotes
TRUENAS_URLwss://truenas.local:444Must be wss://. The TrueNAS middleware revokes API keys used over ws://
TRUENAS_API_KEY1-...Generated in TrueNAS UI: User → API Keys → Add. Key needs admin scope for the actions you intend to run
TRUENAS_VERIFY_SSLfalseSet 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 with confirm: true and a reason string 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_filters operations).

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 permissive Record<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.query reads still surface SSH public keys.
  • Per-connection TLS settings. No process.env.NODE_TLS_REJECT_UNAUTHORIZED mutation. The verifySsl flag 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-mcpspranab/truenas-mcptruenas/truenas-mcp
TransportWebSocketRESTWebSocket
Action coverage270 (17 categories)~278 (18 categories)52 flat tools
ZFS dataset opsFull CRUD + snapshotsFull CRUD + snapshotscreate_dataset and query_datasets only
Safety model4-tier, centralizedPer-handler confirmDry-run preview
Response filteringCentralized 3-layerNonePer-handler hand-crafted masking
Tests / CI226 / yes0 / no27 / yes
LicensePolyForm-NC 1.0.0MITGPL-3.0
Statusv1.1.1Single-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 a settled flag on each pending request and routing both timer and message paths through a single settlePending() state-transition function.
  • Send-error orphan. ws.send runs 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, with try/catch around 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 typed ReconnectAborted error for the non-retryable cases.
  • system.general.update schema was Record<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_key family.

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.

Ver o original no GitHub

Bom para

Relacionados