Which integrations are available for this server?

Provides read-only access to TrueNAS SCALE storage (pools, disks, datasets, snapshots), shares (SMB, NFS), services, system info, jobs, and alerts via the JSON-RPC 2.0 WebSocket API.

How do I use truenas-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@truenas-mcp what's the status of my storage pools?" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

truenas-mcp

by profanter-dev

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

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+

Related MCP server: truenas-aiops

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

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

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing

ResponsivenessNo issues

Resources

Need Help?

Related Servers

Related MCP Connectors

SRI — MCP Server Inspector A
biz.sri-test
2,000+ MCP servers read at source level. Know what one does before you connect. Free, no key.
Developer Tools
21
AIStatusDashboard
io.github.aistatusdashboard
Read-only MCP server for AIStatusDashboard status, incidents, metrics, and fallback recommendations.
Monitoring Observability
2
FarmNeural Public API
com.farmneural
Public, read-only MCP server for FarmNeural company facts, packages, and capabilities.
Documentation Access Developer Tools
1
ambiscribe
io.ambiscribe
Read-only MCP access to a documented IT fleet: state, changes, posture. 15 tools.
Monitoring Observability Security
2

Related MCP Servers

truenas-ws-mcp
Virtualization File Systems Networking & Infrastructure
thoriphes
A
license
B
quality
D
maintenance
MCP server for TrueNAS Scale that enables AI assistants to manage storage pools, datasets, apps, VMs, snapshots, and more via the native WebSocket API.
Updated 6 months ago (2026-03-26 15:28 UTC)
59
MIT
truenas-aiops
File Systems OS Automation Monitoring
AIops-tools
A
license
A
quality
A
maintenance
AI-powered MCP server for TrueNAS SCALE storage operations with governance and safety features, enabling management of pools, datasets, snapshots, disks, alerts, and services.
Updated 4 days ago (2026-09-16 23:27 UTC)
25
MIT
truenas-mcp
File Systems Virtualization Monitoring
cedricziel
A
license
Not graded
quality
A
maintenance
An MCP server for TrueNAS SCALE that enables read-first management of storage, system, sharing, and virtualization resources with per-user API key authentication, and optional write operations.
Updated a day ago (2026-09-19 16:43 UTC)
1
MIT
MCP-TrueNAS
Monitoring Networking & Infrastructure Virtualization
PainInTheNic
A
license
A
quality
B
maintenance
An MCP server that lets Claude monitor and manage a TrueNAS box in plain English. It is deliberately read-only, providing tools to check alerts, storage pools, snapshots, services, and more.
Updated 6 days ago (2026-09-15 14:20 UTC)
18
1
MIT

truenas-mcp

Requirements

Install

Configuration

TrueNAS (required)

Docker proxy (optional)

Claude Code setup

Tools

Storage

Shares

Services

System

Apps

Docker containers (optional — requires Docker proxy)

Jobs & Alerts

Docker proxy setup

Protocol details

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

truenas-ws-mcp

truenas-aiops

truenas-mcp

MCP-TrueNAS