truenas-aiops
This server provides governed TrueNAS SCALE storage operations over MCP, combining read-only health/triage with limited audited write actions and undo support.
Inspect system health and inventory: overview, system info, pools, datasets, snapshots, disks, S.M.A.R.T. results, alerts, services, replication, and cloud-sync tasks.
Run diagnostics/RCA: pool health by state/error counters/capacity; alerts and near-full datasets with worst-first findings.
Perform governed writes: start pool scrub, create datasets, create/delete snapshots, restart services, and apply recorded undo tokens.
Preview writes with dry-run where supported; destructive/high-risk actions are labeled and audited.
Record audit rows and undo tokens for reversible actions; snapshot creation records inverse snapshot deletion.
Use encrypted credential storage and automatic TrueNAS transport selection (REST v2.0 or JSON-RPC/WebSocket).
It does not enforce policy/approval gates; permission is owned by the TrueNAS API key/account and writes can be prevented by scoping credentials.
Provides tools for managing TrueNAS SCALE storage operations, including pools, datasets, snapshots, disks, alerts, services, and replication/cloud sync tasks.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@truenas-aiops list current alerts"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
TrueNAS AIops
Audit availability: Real writes require a committed
pendingaudit row and stop before contacting the platform if storage is unavailable. Reads and previews may continue with a warning; new audit rows store outcome summaries rather than full responses.
Disclaimer: Community-maintained open-source project. Not affiliated with, endorsed by, or sponsored by iXsystems or the TrueNAS project. "TrueNAS" is a trademark of its owner. MIT licensed.
AI-powered TrueNAS SCALE storage operations with a built-in governance harness — unified audit log, token/runaway budget guard, undo-token recording, and descriptive risk tiers. Speaks both TrueNAS APIs: REST v2.0 and the JSON-RPC/WebSocket API that replaces it in TrueNAS 26.
Verification status: live-verified against a real TrueNAS SCALE 25.04.2.1 appliance over both transports, including a full write → audit → undo → verified-restore loop. Coverage is listed endpoint by endpoint — and so are the gaps — in docs/VERIFICATION.md. Read it rather than reading "verified" as "everything".
Supported TrueNAS versions — and which API you are speaking
truenas-aiops speaks both TrueNAS APIs and picks the one that will still
exist:
TrueNAS version | REST API v2.0 | JSON-RPC over WebSocket | what this tool does |
≤ 25.10.0 | supported | — | REST |
25.04 – 25.10.x | deprecated (every call raises an appliance alert) | already served at | WebSocket (auto) |
26 and newer | removed | required | WebSocket |
Set transport: per target in config.yaml:
targets:
- name: nas1
host: nas1.example.com
transport: auto # default — probe /api/current, prefer WebSocket
# transport: websocket # pin the API that survives TrueNAS 26
# transport: rest # pin REST while migratingauto probes /api/current with a cheap HTTP upgrade (no credential spent). If
the appliance offers it, the tool uses it; otherwise it falls back to REST,
which is still correct on 25.10 and older.
iXsystems documents that upgrading to TrueNAS 26 revokes existing API keys — so expect to mint a new one after the upgrade. We have not reproduced this ourselves; it is reported here from the upstream release notes, not from a verified upgrade. Treat it as a caution, not a measurement.
truenas-aiops doctor tells you which transport the connection actually used,
reads the server version, and — on REST — says plainly whether REST is
supported, deprecated, or gone. If the version cannot be parsed it reports
UNKNOWN, never a clean bill of health it cannot justify.
Related MCP server: TrueNAS Scale MCP Server
What works
CLI (
truenas-aiops ...):init,overview,system,pool list/get/status/scrub-status/capacity/scrub-start,dataset list/get/create,diagnose pool-health/alerts,snapshot list/create/delete,disk list/smart,alert list,service list/restart,replication list/cloudsync,secret set/list/rm/migrate/rotate-password,doctor,mcp.MCP server (
truenas-aiops mcportruenas-aiops-mcp): 25 tools (19 read, 6 write), every one wrapped with the bundled@governed_toolharness.Encrypted credentials: the TrueNAS API key lives in an encrypted store
~/.truenas-aiops/secrets.enc(Fernet + scrypt) — never plaintext on disk. Unlock with a master password fromTRUENAS_AIOPS_MASTER_PASSWORD(MCP/CI) or an interactive prompt (CLI).Reversibility:
snapshot_createrecords an inversesnapshot_deleteundo descriptor. The irreversiblesnapshot_delete(highrisk) captures the snapshot's BEFORE state for the audit record and declares no undo.Safety: destructive CLI ops (
snapshot delete,service restart) require double confirmation and support--dry-run.
What this tool does, and does not, decide
It delivers TrueNAS SCALE storage operations — reads and writes — accurately and efficiently, and records every one of them. It does not decide whether a write is allowed to happen. That is the agent's judgement, or the permission of the account you connect it with: scope the TrueNAS API key to a limited-privilege account and the writes fail at the appliance — the place that actually owns the permission.
So there is no read-only switch, no policy file, no approval gate to configure.
The one thing the tool guarantees is that nothing is silent: every call, over
MCP and over the CLI alike, lands an audit row in ~/.truenas-aiops/audit.db,
and reversible writes still capture their before-state and record an inverse.
Each tool declares a
risk_level, kept in agreement with its[READ]/[WRITE]documentation tag by a test, and carried into the audit row as a descriptive tier — so a reviewer can see at a glance that a row was a high-risk delete. It is a label, not a gate.
Running a smaller / local model? See agent-guardrails.md — it lists the guardrails this tool now enforces for you (so you don't spend prompt budget restating them) and gives a ready-made system prompt for what's left.
Playbook: triage a degraded pool
truenas-aiops diagnose pool-health # worst-first: bad state, error counters, capacity
# → e.g. CRITICAL tank "pool status is DEGRADED", and "read=4 checksum=2" on a vdev
truenas-aiops pool status tank # inspect the topology / scan detail it cited
truenas-aiops pool scrub-start tank # kick an integrity scrub (governed, medium risk)
truenas-aiops diagnose alerts # cross-check active alerts + any datasets near fullEach finding cites the measured number that tripped it (status string, error counts, used-percent) so you see why it was flagged, then points at the exact read/write command to act on it.
Capability matrix (25 MCP tools)
Category | Tools | Count | R/W |
Overview / System |
| 2 | read |
Diagnostics / RCA |
| 2 | read |
Pools |
| 5 | read |
| 1 | write (medium) | |
Datasets |
| 2 | read |
| 1 | write (medium) | |
Snapshots |
| 1 | read |
| 2 | write | |
Disks |
| 2 | read |
Alerts |
| 1 | read |
Services |
| 1 | read |
| 1 | write (medium) | |
Replication |
| 2 | read |
Undo (governance) |
| 1 | read |
| 1 | write (medium) |
Quick start
As a Claude Code plugin
One install gives an agent both the skill and the MCP server:
/plugin marketplace add AIops-tools/marketplace
/plugin install truenas-aiops@aiops-toolsThe MCP server is fetched with uv and pinned to the
package version this plugin declares, so an audit row can be traced back to the
code that wrote it. Credentials are still configured with truenas-aiops init — see below.
As an OpenClaw plugin
The same bundle is published on ClawHub, where one install delivers the skill and its MCP server together:
openclaw plugins install clawhub:@zw008/truenas-aiops
openclaw skills info truenas-aiops # expect: Visible to model: yesRestart the OpenClaw gateway afterwards so it loads the plugin. The MCP server is
fetched with uv, pinned to this exact release, so
uvx has to be on PATH — without it the skill still installs but reports
Visible to model: no. Credentials are configured exactly as below.
As a CLI or standalone MCP server
uv tool install truenas-aiops
truenas-aiops init # interactive wizard: connection details + encrypted API key
truenas-aiops doctor # verify config, encrypted store, connectivity (hits /system/info)init writes ~/.truenas-aiops/config.yaml (non-secret connection details) and
stores the API key encrypted in ~/.truenas-aiops/secrets.enc. Example
config it produces:
targets:
- name: nas1
host: 10.0.0.30
port: 443
verify_ssl: false # self-signed lab certs only
api_path: /api/v2.0Create the API key in the TrueNAS UI under Credentials → API Keys. For non-interactive use (MCP server, CI, cron) export the master password so the store can be unlocked without a prompt:
export TRUENAS_AIOPS_MASTER_PASSWORD='your-master-password'Where that password then lives: an exported variable is readable by every process this shell starts and is recorded by shell history. On a shared or long-lived host, prefer the interactive prompt, or inject it from a secret manager for the life of the one command that needs it.
Managing secrets
truenas-aiops secret set nas1 # prompts hidden for the API key
truenas-aiops secret list # names only, values never shown
truenas-aiops secret rm nas1
truenas-aiops secret rotate-password # re-encrypt under a new master password
truenas-aiops secret migrate # import a legacy plaintext .env, then deletes itA legacy plaintext env var TRUENAS_<TARGET_NAME_UPPER>_APIKEY is still honoured
as a fallback with a deprecation warning (migrate with truenas-aiops secret migrate).
支持范围 / Supported scope
Versions: TrueNAS SCALE 25.04 and newer over JSON-RPC/WebSocket, and any build still serving REST v2.0 over REST — the transport is selected automatically. See Supported TrueNAS versions. Note that iXsystems documents an upgrade to TrueNAS 26 as revoking existing API keys (upstream claim, not reproduced here).
Read: system info, ZFS pools (list/get/status/scrub-status/capacity), datasets
(list/get), snapshots (list), disks + S.M.A.R.T. results, alerts, services,
replication & cloud-sync tasks, one-shot health overview, and read-only
diagnostics / RCA (pool_health_rca, alert_and_capacity_rca). Mutating (governed,
dry-run + double-confirm where destructive): pool_scrub_start,
dataset_create, snapshot_create, snapshot_delete, service_restart.
缺功能?(Missing something?) Coverage is intentionally focused. Open an issue or PR at github.com/AIops-tools/TrueNAS-AIops — feature requests, contributions, and comments are all welcome.
Caveats
Live-verified against TrueNAS SCALE 25.04.2.1 over both transports — reads cross-checked against the appliance's own API, and a full write → audit → undo → verified-restore loop. What is and is not covered is listed endpoint by endpoint in docs/VERIFICATION.md; read it rather than assuming "verified" means everything.
Still unverified: S.M.A.R.T. against failing media (needs real hardware — virtio exposes no S.M.A.R.T. at all), replication/cloudsync against real targets, and TrueNAS 26's
auth.login_ex(25.04 exercises only the fallback).CLI exit codes:
0confirmed,1failed or refused,2outcome undetermined (the operation may still be in flight — poll before retrying).Out of scope by design: anything that destroys bulk data (dataset/pool deletion, replication runs that overwrite) — only
snapshot_deleteremoves data, and it ishighrisk + double-confirmed.
Not for
Other NAS/storage or backup products, hypervisor VM lifecycle, container clusters, or network devices — those are out of scope for this tool.
License
Available Tools
25 toolsalert_and_capacity_rcaARead-only
[READ] Surface active TrueNAS alerts by level and datasets near full.
Collects the active alert list and the /pool/dataset listing, then reports worst-first findings: one per active (non-dismissed) alert at WARNING+ and one per dataset whose usage is near its quota/available ceiling (80%/90%), each citing the measured level/percent.
Args: target: TrueNAS target name from config; omit to use the default.
Inputs: target.
alert_listARead-only
[READ] List active TrueNAS alerts with level, message, class, dismissed.
Args: target: TrueNAS target name from config; omit to use the default.
Inputs: target.
cloudsync_listBRead-only
[READ] List cloud-sync tasks with description, direction, path, state.
state here is the last run's job state (SUCCESS / FAILED / RUNNING) and
is null until the task has run — cloud-sync records, unlike replication
ones, carry no state of their own.
Args: target: TrueNAS target name from config.
Inputs: target.
dataset_createBDestructive
[WRITE] Create a ZFS dataset. Non-destructive (creates new storage). Pass dry_run=True to preview.
No undo descriptor — dataset deletion is intentionally out of scope.
Args: name: Full dataset path including the pool, e.g. 'tank/projects'. pool: Optional pool name for context/labelling. dry_run: If True, preview without creating. target: TrueNAS target name from config.
Inputs: name (required), pool, target, dry_run.
dataset_getBRead-only
[READ] Return detail for a single dataset by id (e.g. 'tank/data').
Args: dataset_id: TrueNAS dataset id (see dataset_list). target: TrueNAS target name from config.
Inputs: dataset_id (required), target.
dataset_listARead-only
[READ] List ZFS datasets with id, name, type, pool, used/available.
Args: target: TrueNAS target name from config; omit to use the default.
Inputs: target.
disk_listARead-only
[READ] List physical disks with name, serial, model, size, pool.
Args: target: TrueNAS target name from config; omit to use the default.
Inputs: target.
overviewARead-only
[READ] One-shot health summary: pools (capacity/health), alerts, services.
Call this first to triage a TrueNAS system before drilling into a specific pool, dataset, or service.
Args: target: TrueNAS target name from config; omit to use the default.
Inputs: target.
pool_capacityBRead-only
[READ] Capacity summary per pool: size/allocated/free and used percent.
Args: target: TrueNAS target name from config.
Inputs: target.
pool_getARead-only
[READ] Return detail for a single pool by id.
Args: pool_id: TrueNAS pool id (see pool_list). target: TrueNAS target name from config.
Inputs: pool_id (required), target.
pool_health_rcaARead-only
[READ] Flag ZFS pools by state, error counters, and capacity.
Pulls the /pool listing (with topology + scan) and flags pools that are DEGRADED/FAULTED/OFFLINE, pools with non-zero read/write/checksum/scan error counters, and pools over the 80%/90% capacity thresholds — worst-first, each finding citing the measured status/counts/percent and a concrete action.
Args: target: TrueNAS target name from config; omit to use the default.
Inputs: target.
pool_listBRead-only
[READ] List ZFS pools with id, name, status, health, capacity.
Args: target: TrueNAS target name from config; omit to use the default.
Inputs: target.
pool_scrub_startADestructive
[WRITE] Start a scrub (integrity check) on a pool. Non-destructive. Pass dry_run=True to preview.
No undo descriptor (a scrub has no clean inverse beyond cancellation). Poll progress with scrub_status; do not re-issue.
Args: pool_name: ZFS pool name (e.g. 'tank'). dry_run: If True, preview without starting the scrub. target: TrueNAS target name from config.
Inputs: pool_name (required), target, dry_run.
pool_statusBRead-only
[READ] Health and scan/topology status of a single pool.
Args: pool_id: TrueNAS pool id. target: TrueNAS target name from config.
Inputs: pool_id (required), target.
replication_listARead-only
[READ] List replication tasks with name, direction, transport, state.
state is the replication task's own state — PENDING / RUNNING /
FINISHED / ERROR / HOLD, matching what the appliance UI shows — and is
never absent, PENDING being what a task reports before its first run. An
ERROR row carries the appliance's error sentence naming what to fix.
Also returns lastSnapshot and lastRun (epoch milliseconds).
Args: target: TrueNAS target name from config; omit to use the default.
Inputs: target.
scrub_statusARead-only
[READ] Current scrub scan state (function/state/percentage) for a pool.
Args: pool_id: TrueNAS pool id. target: TrueNAS target name from config.
Inputs: pool_id (required), target.
service_listARead-only
[READ] List system services with name, state (RUNNING/STOPPED), enable.
Args: target: TrueNAS target name from config; omit to use the default.
Inputs: target.
service_restartADestructive
[WRITE] Restart a system service (e.g. 'smb', 'nfs'). Pass dry_run=True to preview.
Captures the prior service state for the audit record; declares no undo (a restart is not cleanly reversible).
Refuses a service name that is not present in service_list, and refuses 'ssh' unless confirm=True — SSH is the out-of-band recovery path, and bouncing it can strand whoever is working over it. Both refusals apply under dry_run too, which must report a refusal rather than preview a call that will be refused.
Args: service: TrueNAS service name (see service_list). confirm: Required (True) only to restart 'ssh'; ignored otherwise. dry_run: If True, preview without restarting. target: TrueNAS target name from config.
Inputs: service (required), target, confirm, dry_run.
smart_test_resultsBRead-only
[READ] Recent S.M.A.R.T. self-test results per disk (status/description).
Args: target: TrueNAS target name from config.
Inputs: target.
snapshot_createADestructive
[WRITE] Create a ZFS snapshot 'dataset@name'. Inverse: snapshot_delete. Pass dry_run=True to preview.
Args: dataset: Dataset path to snapshot (e.g. 'tank/data'). name: Snapshot name (e.g. 'manual-2026-06-28'). dry_run: If True, preview without creating (and without an undo token). target: TrueNAS target name from config.
Inputs: name (required), dataset (required), target, dry_run.
snapshot_deleteADestructive
[WRITE] Delete a ZFS snapshot by id ('dataset@name'). IRREVERSIBLE. Pass dry_run=True to preview.
Captures the snapshot's prior state for the audit record; declares no undo.
Args: snapshot_id: Full snapshot id 'dataset@name' (see snapshot_list). dry_run: If True, preview without deleting. target: TrueNAS target name from config.
Inputs: snapshot_id (required), target, dry_run.
snapshot_listARead-only
[READ] List ZFS snapshots, optionally filtered to one dataset.
Returns {"snapshots": [...], "returned": N, "limit": L, "truncated": bool}. When "truncated" is true there are more snapshots than were returned — re-run with a higher limit or filter to one dataset.
Args: dataset: Optional dataset path to filter (e.g. 'tank/data'). limit: Max snapshot rows to return (default 200). target: TrueNAS target name from config.
Inputs: limit, target, dataset.
system_infoBRead-only
[READ] TrueNAS system summary: version, hostname, memory, cores, uptime.
Args: target: TrueNAS target name from config; omit to use the default.
Inputs: target.
undo_applyADestructive
[WRITE][risk=medium] Apply a recorded undo by dispatching its inverse tool.
The inverse runs through its own governed tool, so it is audited under its own risk tier. Pass dry_run=True to preview the inverse call without executing it. A token can only be applied once.
Args:
undo_id: The undoId from undo_list (or an _undo_id in a write result).
dry_run: If True, preview the inverse tool + params without running it.
target: Passed through to the inverse tool when it accepts a target.
Inputs: undo_id (required), target, dry_run.
undo_listARead-only
[READ] List recorded, not-yet-applied undo tokens (most recent first).
Each entry names the original tool, the inverse tool that undo_apply
would run, and a human note. Use the undoId with undo_apply.
Returns {"undos": [...], "returned": N, "limit": L, "truncated": bool}. When "truncated" is true there are more recorded tokens than were shown — re-run with a higher limit rather than treating the list as complete. One extra row is fetched so "truncated" is measured, not guessed from a length coincidence.
Each entry carries effectVerified. False means the original write
lost its response, so the change it reverses is PROBABLE, not confirmed —
check the live state before applying, and do not report the result as a
restore of a state that may never have been reached.
Args: limit: Max rows to return (default 50, hard cap 500). target: Unused (undo state is host-local); accepted for CLI uniformity.
Inputs: limit, target.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 25 tools
Pool-related reads overlap heavily: pool_get, pool_status, pool_capacity, and pool_health_rca all describe per-pool health/capacity/scan info, and overview vs pool_health_rca vs alert_and_capacity_rca present competing 'triage' summaries. Descriptions differentiate them somewhat (RCA tools do worst-first flagging, overview is a summary), but an agent could easily misselect among them. The write/undo tools and snapshot/dataset/service tools are otherwise distinct.
The set follows a mostly predictable noun_verb snake_case convention (dataset_list, pool_get, snapshot_create, service_restart, undo_apply). A few outliers like 'overview' and 'smart_test_results' deviate slightly, but nothing is jarring or mixed-convention. Readable and largely consistent.
25 tools sits at the heavy end of the scale, and several reads (overview, pool_health_rca, alert_and_capacity_rca, pool_get, pool_status, pool_capacity) feel like redundant coverage of the same triage surface. The set is workable but not tight; some consolidation would earn each tool's place more clearly.
Coverage spans pools, datasets, snapshots, disks, SMART, alerts, services, replication, cloudsync, and system info, plus a governed write/undo mechanism. Gaps exist — no dataset delete/update (explicitly out of scope), no pool create/destroy, no share (SMB/NFS) or user management, no snapshot rollback — but these are workable around the core storage-admin workflows.
Maintenance
Related MCP Connectors
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
AI governance MCP server for EU AI Act compliance and jurisdiction verification
MCP server for Gainium — manage trading bots, deals, and balances via AI assistants
Hosted MCP server for AI-driven data ops. Create apps, manage schemas, and CRUD structured data.
Related MCP Servers
- AlicenseBqualityDmaintenanceA Model Context Protocol server that enables Claude Desktop and other MCP clients to interact with TrueNAS Core systems through the TrueNAS API, supporting user management, storage operations, sharing, and snapshot creation.20130 PyPI35MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server that enables AI assistants to manage TrueNAS Scale Custom Apps using natural language commands, with tools for deploying, managing, and monitoring Docker Compose applications.7MIT
- AlicenseBqualityDmaintenanceMCP server for TrueNAS Scale that enables AI assistants to manage storage pools, datasets, apps, VMs, snapshots, and more via the native WebSocket API.59MIT
- AlicenseAqualityBmaintenanceAn MCP server for TrueNAS that lets users manage ZFS pools, datasets, shares, snapshots, VMs, alerts, and network configuration through natural language, using a single hierarchical tool exposing 278 actions.132 npm1MIT