truenas-mcp

MCP server for TrueNAS SCALE 25.10+ and the Docker containers running on it. Runs as a container on the NAS and serves MCP over Streamable HTTP. Talks to TrueNAS via the JSON-RPC 2.0 WebSocket API and to Docker via the local socket.

Why this exists: The official truenas/truenas-mcp binary uses the legacy DDP protocol, which was removed in TrueNAS 25.10. This server targets the new wss://host/api/current JSON-RPC 2.0 endpoint exclusively.

Read-only by default. All TrueNAS tools are read-only. Docker write tools (start/stop/restart, update/rollback, image pull/prune) exist but are only registered when DOCKER_WRITE_TOOLS=true.

Upgrading from 1.x? The npm package @profanter-dev/truenas-mcp (stdio, npx) is deprecated. 2.x ships only as the container image ghcr.io/profanter-dev/truenas-mcp — see Migrating from 1.x.

Requirements

• TrueNAS SCALE 25.10 or later, with Docker (e.g. stacks managed by Dockge)

• A TrueNAS API key (generate in System → API Keys)

Related MCP server: truenas-aiops

Deploy

Deploy as a Dockge stack (or plain docker compose) on the NAS. A full example with Traefik labels is in compose.example.yml:

services:
  truenas-mcp:
    image: ghcr.io/profanter-dev/truenas-mcp:latest
    restart: unless-stopped
    environment:
      TRUENAS_HOST: 192.168.1.29:444
      TRUENAS_API_KEY: ${TRUENAS_API_KEY}
      TRUENAS_INSECURE: "true"
      MCP_AUTH_TOKEN: ${MCP_AUTH_TOKEN}
      STACKS_DIR: /mnt/apps/stacks
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /proc:/host/proc:ro   # optional: host processes for process_list
      - /mnt/apps/stacks:/mnt/apps/stacks:ro   # optional: compose files for stack_list/stack_compose (same path as on the host)
    group_add:
      - ${DOCKER_GID}   # stat -c %g /var/run/docker.sock
    read_only: true
    cap_drop: [ALL]
    security_opt: [no-new-privileges:true]

The image runs as the unprivileged node user; group_add gives it access to the Docker socket. Generate the bearer token with openssl rand -hex 32.

GET /healthz (unauthenticated) reports { truenas, docker, version } and backs the image's HEALTHCHECK.

Configuration

Claude Code setup

claude mcp add --transport http truenas https://truenas-mcp.example.com/mcp \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>"

Or on the LAN without Traefik, publish the port (ports: ["3000:3000"]) and use http://<nas-ip>:3000/mcp.

Tools

All entities follow a consistent list / details pattern. TrueNAS timestamps are returned in the NAS's configured timezone with their UTC offset (e.g. 2026-10-25T02:00:10+01:00), so they read as local time and stay unambiguous across DST changes.

Storage

TrueNAS 25.10 removed the SMART test API, so SMART results are not available; disk health shows up as alerts (alert_list) and ZFS error counts.

Shares

Services

System

Apps

Note: These tools cover apps installed via the TrueNAS Apps UI (catalog apps). Docker Compose stacks managed by external tools such as Dockge are not visible through the TrueNAS WebSocket API — use the container tools below instead.

Docker containers

Registered when the Docker socket is mounted.

Updates

Diagnostics

process_list needs the host's /proc mounted read-only (/proc:/host/proc:ro). Without it, it falls back to per-container ps output (container processes only, lifetime-average CPU).

Docker write tools (opt-in: DOCKER_WRITE_TOOLS=true)

Stop/restart/update refuse to act on the MCP server's own container. Write tools carry MCP destructiveHint annotations so clients can ask for confirmation.

How container_update works

Containers are recreated from their own configuration via the Docker API — no compose files needed, and Dockge still sees them as part of their stack:

1. Pull the tag; stop if the image is unchanged (unless force).

2. Build the new container from the old one's config, dropping values inherited from the old image (ENV, labels, CMD, …) so the new image's defaults apply. Auto-assigned MAC addresses and hostnames are not copied; anonymous volumes are re-attached by name.

3. Stop dependents sharing its network (network_mode: service:X), stop it, rename it to <name>-old-<timestamp>, create and start the new one.

4. Wait until it is healthy (healthcheck) or stays up for 10 s (no healthcheck).

5. Recreate the dependents against the new container, then delete the old containers.

Rollback is only automatic when the new version never ran — Docker refused to create or start it (port in use, missing mount, …). If it started and then crashed, turned unhealthy or timed out, it may already have migrated data, so it is left untouched (not even stopped) and the old container is kept stopped as <name>-old-<timestamp>. Inspect its logs (included in the result) and fix forward, or call container_rollback deliberately.

Jobs & Alerts

Scheduled & data-protection tasks

Security

Access to the Docker socket is root-equivalent on the host, and mounting it :ro does not change that — it only protects the socket file, not the API behind it. This server is therefore the security boundary:

• src/docker-client.ts checks every request against a fixed allowlist of method + path (read endpoints, start/stop/restart, image pull/prune, and the create/rename/delete steps of an update). Query strings are built internally; there is no generic passthrough, exec, build, volume or network access.

• /containers/create is only reached through the update path, whose body is always derived from an existing container's inspect output — tool arguments can't supply container configuration, mounts or privileges. Containers are never deleted with their volumes.

• The /proc mount is read-only; process command lines are redacted for passwords, tokens and URL credentials.

• The stacks mount is read-only. Only compose files and .env are read, only after their real path is confirmed to be inside STACKS_DIR (no tool argument is used as a path); .env values are never returned, and secret-looking compose values are redacted.

• /mcp requires the bearer token; comparison is constant-time.

• Run the container read-only, without capabilities, as non-root (see the compose example), and keep it behind TLS (e.g. Traefik) if it is reachable beyond the LAN.

Development

cp .env.example .env   # fill in values
yarn install
yarn dev               # tsx src/index.ts, serves on :3000
docker build --build-arg APP_VERSION=dev -t truenas-mcp:dev .

Releases: pushing a v* tag builds and publishes ghcr.io/profanter-dev/truenas-mcp (X.Y.Z, X.Y, X, latest) and creates a GitHub release.

Migrating from 1.x

1. Deploy the container as above (the docker-socket-proxy stack is no longer needed).

2. Replace the stdio registration:

   claude mcp remove truenas
   claude mcp add --transport http truenas https://truenas-mcp.example.com/mcp \
     --header "Authorization: Bearer <MCP_AUTH_TOKEN>"

3. DOCKER_PROXY_URL / DOCKER_PROXY_USER / DOCKER_PROXY_PASS are gone; the socket mount replaces them.

Protocol details

• WebSocket URL: wss://<host>/api/current

• Auth: auth.login_with_api_key — called once on connect; never reconnects per-call

• Rate limit: TrueNAS enforces 20 auth attempts per 60 s; exceeding triggers a 10-minute lockout

• The server maintains a single persistent connection, shared by all MCP clients, with exponential-backoff reconnection on unexpected disconnects