TrueNAS AIops MCP server

<!-- mcp-name: io.github.AIops-tools/truenas-aiops -->

TrueNAS AIops

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:

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 migrating

auto 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.

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 mcp or truenas-aiops-mcp): 25 tools (19 read, 6 write), every one wrapped with the bundled @governed_tool harness.
• 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 from TRUENASAIOPSMASTER_PASSWORD (MCP/CI) or an interactive prompt (CLI).
• Reversibility: snapshotcreate records an inverse snapshotdelete undo descriptor. The irreversible snapshot_delete (high risk) 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

Shortened. The full README is on GitHub.