Configuration¶
truenas-mcp has 1 command, serve, and takes its settings from flags or from
environment variables. A flag that is set wins over its variable.
Commands¶
| Command | What it does |
|---|---|
truenas-mcp serve |
Connect to the appliance, sign in with the API key, and serve MCP over stdio. |
truenas-mcp completion <shell> |
Print the completion script for bash, zsh, fish or powershell. |
truenas-mcp --version |
Print the version and the commit. |
truenas-mcp --help |
Print the usage. |
serve settings¶
| Flag | Environment variable | Default | Meaning |
|---|---|---|---|
--host |
TRUENAS_HOST |
none, required | The appliance host name or IP address, for example truenas.local. Not a URL. |
--api-key |
TRUENAS_API_KEY |
none, required | The TrueNAS API key the server signs in with. |
--enable-writes |
TRUENAS_ENABLE_WRITES |
off | Register the write tools. See read-only by default. |
--tls-insecure |
TRUENAS_TLS_INSECURE |
off | Skip the TLS certificate check. Use it only for a self-signed certificate whose risk you accept. |
A boolean variable is on for 1, t, true, y, yes or on, and off
for 0, f, false, n, no or off, in any of the case forms in
read-only by default.
Any other value keeps the default.
When --host or --api-key has no value, serve exits with an error that
names the flag and its variable.
Keep the API key off the command line
A value in --api-key is visible to other users of the machine in the
process list, and stays in your shell history. Prefer
TRUENAS_API_KEY, read with read -rs or set by your MCP client.
Connect an MCP client¶
An MCP client starts the server as a child process and speaks MCP over its
stdin and stdout. For Claude Code, and for clients that use the same
mcpServers format, the entry is:
{
"mcpServers": {
"truenas": {
"command": "/absolute/path/to/truenas-mcp",
"args": ["serve"],
"env": {
"TRUENAS_HOST": "truenas.local",
"TRUENAS_API_KEY": "<your API key>"
}
}
}
}
The client's configuration file then holds the API key: keep its permissions
tight. Add "--enable-writes" or "--tls-insecure" to args only when you
need them.
Connection behavior¶
- The server connects to
wss://<host>/api/currentand signs in with the API key. - TLS certificate verification is on by default.
- Before each call, the server checks the connection with
core.ping. When the check fails, it connects and signs in again. - Calls are serialized: 1 call to the appliance at a time.
- The server never sends a call again after a transport error, because a write may already have taken effect. It reports the error, and the next call opens a fresh connection.
Supported TrueNAS releases¶
truenas-mcp supports TrueNAS SCALE Goldeye (25.10) and later. The API audit checked the middleware methods of the tools against a live TrueNAS 27.0.0-RC.1 on 2026-10-22. It also records later checks of methods that later tools added, against a live appliance or against the middleware source. The audit lists the fallbacks for older releases too.