TrueNAS MCP
# TrueNAS MCP
An MCP server that turns your TrueNAS (SCALE) instance into tools. Manage pools,
disks, datasets, apps, VMs and more from any MCP client. Built on FastMCP and the
official `truenas_api_client` websocket library.
Authenticated with a TrueNAS API key over a persistent websocket connection.
Targets TrueNAS 25.10 (pin: `TS-25.10.3`).
## Run with Docker
You need a TrueNAS instance and an API key (Account Settings > API Keys).
```bash
docker build -t truenas-mcp .
docker run -e TRUENAS_URI=wss://truenas.example.com/api/current \
-e TRUENAS_API_KEY=your-key \
truenas-mcp
```
## Settings
| name | default | notes |
| ---- | ------- | ----- |
| `TRUENAS_URI` | - | required, ws:// or wss:// websocket URL, e.g. `wss://host/api/current` |
| `TRUENAS_API_KEY` | - | required, from TrueNAS API Keys |
| `TRUENAS_VERIFY_SSL` | true | set false only over plain `ws://` (disable TLS verification for self-signed) |
| `LOG_LEVEL` | INFO | |
Values can come from a `.env` file in the working directory. API-key auth uses
`auth.login_with_api_key` over the persistent connection (TrueNAS 25.10 SCRAM -
no username needed).
## Serve over HTTP
By default the server talks stdio (one process per client). To expose it as an
HTTP MCP endpoint behind a gateway (e.g. LiteLLM), set the FastMCP transport
env vars - no code change required:
| env | default |
| --- | ------- |
| `FASTMCP_TRANSPORT` | `stdio` |
| `FASTMCP_HOST` | `127.0.0.1` |
| `FASTMCP_PORT` | `8000` |
| `FASTMCP_STREAMABLE_HTTP_PATH` | `/mcp` |
Example - serve streamable-http on all interfaces:
```bash
FASTMCP_TRANSPORT=streamable-http FASTMCP_HOST=0.0.0.0 FASTMCP_PORT=8000 \
truenas-mcp
```
## Tools
`system_info`, `list_pools`, `list_disks`, `list_datasets`, `list_apps`,
`list_vms`, `truenas_call` (generic middleware escape hatch).
## License
MIT
TDQS
Scored across 29 tools
Most tools target clearly distinct resources and actions, especially the list/create/delete families for datasets, snapshots, and shares. Minor ambiguity exists between update_app and upgrade_app, and truenas_call overlaps with every specific tool as a generic escape hatch.
Almost all tools use consistent snake_case verb_noun naming, such as list_pools, create_dataset, and delete_share. The few deviations are system_info (noun-first) and truenas_call (noun_verb), but the overall pattern remains predictable.
TrueNAS is a broad administration domain, so many tools are justified, but 29 tools is on the heavy side and includes both granular wrappers and a generic truenas_call fallback. The set is useful but close to feeling over-expanded.
Core areas like datasets, snapshots, shares, apps, alerts, and scrubs are well covered, but VM support is list-only and there are no update operations for datasets or shares. The generic truenas_call endpoint can fill gaps, though not as cleanly as dedicated tools.