truenas-mcp

Read-only MCP server for TrueNAS SCALE 25.10+ — connects via the JSON-RPC 2.0 WebSocket API.

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: This server performs zero write or mutating operations.

---

Requirements

• TrueNAS SCALE 25.10 or later
• A TrueNAS API key (generate in System → API Keys)
• Node.js 18+

---

Install

npm install -g @profanter-dev/truenas-mcp

Or run without installing:

npx @profanter-dev/truenas-mcp

---

Configuration

TrueNAS (required)

Variable	Required	Description
TRUENAS_HOST	✓	host:port, e.g. 192.168.1.29:444
TRUENAS_API_KEY	✓	TrueNAS API key
TRUENAS_INSECURE		true to skip TLS certificate verification (self-signed certs)

Docker proxy (optional)

Enables container_list, container_details, and container_logs. See Docker proxy setup below.

Variable	Required	Description
DOCKER_PROXY_URL	✓	Base URL of the docker-socket-proxy, e.g. https://docker.example.com
DOCKER_PROXY_USER	✓	Basic auth username
DOCKER_PROXY_PASS	✓	Basic auth password

Copy .env.example to .env and fill in your values, or pass as environment variables.

---

Claude Code setup

claude mcp add truenas \
  -e TRUENAS_HOST=192.168.1.29:444 \
  -e TRUENAS_API_KEY=your-key \
  -e TRUENAS_INSECURE=true \
  -- npx @profanter-dev/truenas-mcp

---

Tools

All entities follow a consistent list / details pattern.

Storage

Tool	Description
pool_list	All ZFS pools — health, status, usable capacity (used + available)
pool_details	Single pool: health, capacity, last scrub
disk_list	All disks — model, type, pool assignment, temperature, SMART result, ZFS error counts
disk_details	Single disk: serial, size, temperature, full SMART history, vdev assignment, ZFS errors
dataset_list	All ZFS datasets with used/available space; optionally filter by pool
dataset_details	Full properties for a single dataset: compression, dedup, quota, and more
snapshot_list	ZFS snapshots ordered newest-first; filter by dataset, configurable limit, boot-pool excluded by default
snapshot_details	Single snapshot: size, referenced, compression ratio, clones

Shares

Tool	Description
share_list	All SMB and NFS shares — path, enabled state, comment
share_details	Full config for a single SMB or NFS share

Services

Tool	Description
service_list	All TrueNAS services with running state and boot-enable flag
service_details	Single service state plus service-specific config (e.g. SSH port and auth settings, SMB workgroup, NFS settings). Private/public key material is stripped.

System

Tool	Description
system_info	Hostname, version, CPU, memory, uptime, load average (1/5/15 min), timezone

Apps

Tool	Description
app_list	All installed TrueNAS catalog apps with state, version, and update availability
app_details	Single app: state, version, portals, active workloads, notes
app_logs	Recent log output for a TrueNAS catalog app

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 accessible through the TrueNAS WebSocket API — use the Docker proxy tools below instead.

Docker containers (optional — requires Docker proxy)

Tool	Description
container_list	All Docker containers (running and stopped) — name, image, state, health
container_details	Single container: image, state, ports, mounts, networks, labels. Secret env vars are redacted.
container_logs	Recent log output for a container; configurable line count (default 100)

These tools are only registered when DOCKER_PROXY_URL is set.

Jobs & Alerts

Tool	Description
job_list	Unique job types with last-run status and timestamp (cron jobs shown with human-readable description)
job_history	Full run history for a specific job; requires description (from job_list) and limit
alert_list	Active alerts sorted by severity: CRITICAL → ERROR → WARNING → NOTICE → INFO

---

Docker proxy setup

The Docker container tools connect to a tecnativa/docker-socket-proxy instance secured behind Traefik with basic auth. Deploy this as a Dockge stack on your TrueNAS:

# docker-socket-proxy/compose.yml
services:
  docker-proxy:
    image: tecnativa/docker-socket-proxy:latest
    environment:
      CONTAINERS: "1"
      INFO: "1"
      IMAGES: "1"
      NETWORKS: "1"
      POST: "0"   # read-only — block all write operations
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    networks:
      - traefik_network
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.docker-proxy.rule=Host(`docker.example.com`)"
      - "traefik.http.routers.docker-proxy.entrypoints=websecure"
      - "traefik.http.routers.docker-proxy.tls.certresolver=letsencrypt"
      - "traefik.http.routers.docker-proxy.middlewares=docker-proxy-auth"
      - "traefik.http.middlewares.docker-proxy-auth.basicauth.users=admin:$$apr1$$..."
      - "traefik.http.services.docker-proxy.loadbalancer.server.port=2375"
    restart: unless-stopped

networks:
  traefik_network:
    external: true

Generate the htpasswd entry (double $ signs are required in compose labels):

# Install apache2-utils if needed, then:
htpasswd -nb admin yourpassword | sed 's/\$/\$\$/g'

Then set the env vars when registering the MCP server:

claude mcp add truenas \
  -e TRUENAS_HOST=192.168.1.29:444 \
  -e TRUENAS_API_KEY=your-key \
  -e TRUENAS_INSECURE=true \
  -e DOCKER_PROXY_URL=https://docker.example.com \
  -e DOCKER_PROXY_USER=admin \
  -e DOCKER_PROXY_PASS=yourpassword \
  -- npx @profanter-dev/truenas-mcp

---

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 with exponential-backoff reconnection on unexpected disconnects