Skip to content

truenas-mcp

truenas-mcp

An MCP server that exposes TrueNAS SCALE management capabilities to AI assistants. It connects to a TrueNAS SCALE appliance through the WebSocket JSON-RPC API and gives an AI client tools for storage, sharing, system and app management over stdio. It starts read-only: tools that change the appliance exist only when you enable them.

Install truenas-mcp → Make the first connection

Install truenas-mcp covers the requirements, the release packages and the build from source.

What truenas-mcp gives you

  • One view of the appliance


    Tools list pools, datasets, snapshots, shares, alerts, apps and jobs. Reports such as truenas_health_report and truenas_protection_report combine several queries into 1 answer.

  • Read-only by default


    A plain truenas-mcp serve registers only the 24 read-only tools. The 20 write tools exist only with --enable-writes. See read-only by default.

  • Plain configuration


    2 required settings, the appliance host and an API key, as flags or environment variables. See configuration.

  • No replay of writes


    The server checks the connection before each call and reconnects when the check fails. It never sends a call again after a transport error, because a write may already have taken effect.

Start here

  • 01 Install

    Download a release or build truenas-mcp from source.

  • 02 First connection

    Connect to a real appliance in read-only mode.

  • 03 Tools

    Look up every tool, its parameters and its safety class.

  • 04 Build from source

    Build the server and this site yourself.