katbyte/truenas-mcp

An MCP server, CLI and Go SDK for looking after a TrueNAS from Claude Code, Claude Desktop, or any other MCP client.
**It was made mainly to get a Go SDK for truenas-exporter.** A server with a tool for much of the NAS tests an SDK far harder than an exporter that reads a handful of things. So the SDK lives here, and the exporter imports it.
**This is being built.** What works today is the Go connection to a TrueNAS, a typed client with a method for every API call, a stand-in NAS to test against, and an MCP server with its first tools: which NAS it is, its pools down to each disk, its datasets, its disks and its alerts. The rest of the tools are being built on the typed client.
**Detection is code, correction is judgment.** The checks that are coming only report what is wrong. Nothing on a NAS is changed unless a separate tool is asked to change it.
Install
It needs Go, and a TrueNAS 25.04 or later. There is no release yet.
Quick start
Make an API key in the TrueNAS interface (Credentials, then API Keys), and note the user it is made for.
A TrueNAS comes with a certificate nothing trusts. Download it (Credentials, then Certificates) and pass it with --certificate-file. Connecting has the other ways, and how the key is kept safe.
Register the server with Claude Code. It only reads unless --enable-write is given.
What is here
| | |
|---|---|
| sdk/truenasrpc | the connection to a TrueNAS |
| sdk/truenas | a typed client with a method for every API call, generated from TrueNAS's own description |
| sdk/truenastest | a stand-in TrueNAS for tests |
| tools | the MCP tools, and which of them a session gets |
| truenas-mcp serve | the MCP server, over stdio or HTTP |
| truenas-mcp tools | lists the tools the flags would load, with no NAS |
| truenas-mcp info | checks an address, a certificate and a key |
What is coming: the rest of the tools, built on the typed client.
Audits
Each audit only reports, and changes nothing. Audits has every rule.
| audit | what it catches |
|---|---|
| audit_all | every audit below at once, counted by audit and severity: where to start |
| audit_pools | an unhealthy pool, a disk gone or counting errors, a scrub that found errors, a pool not scrubbed lately or with no scrub task |
| audit_space | a pool past 80% full, a dataset near or at its quota or refquota |
| audit_disks | a disk too hot for its kind or past its maker's limit, a disk whose SMART checks failed or report errors |
| audit_tasks | a snapshot task, replication, copy task, cloud sync or cloud backup that failed, is held, copies a locked dataset or is switched off |
| audit_system | an alert the NAS raised, a certificate run out or running out, a service set to start that is stopped, an update waiting |
Settings
| flag | environment | what it is |
|---|---|---|
| --server | TRUENAS_SERVER | the NAS's address, or unix:// on the NAS itself |
| --username | TRUENAS_USERNAME | the user the API key was made for |
| --token | TRUENAS_TOKEN | the API key |
| --token-file | TRUENAS_TOKEN_FILE | a file holding the key, in place of --token |
| --certificate-file | TRUENAS_CERTIFICATE_FILE | the NAS's own certificate, as a PEM file |
| --ca-file | TRUENAS_CA_FILE | the authority that signed the NAS's certificate |