truenas-mcp

truenas-mcp-plugin

Claude Code plugin that bundles the truenas-mcp server plus opinionated skills and slash commands for managing TrueNAS Scale apps in the pvnkn3t infrastructure.

What this plugin gives you

Component	Purpose
MCP server (truenas)	15 tools for system info, app lifecycle, deployment, monitoring
Skill truenas-deploy-and-verify	Safe deploy pipeline: validate → deploy → verify → diagnose on failure
Skill truenas-troubleshoot	Diagnose a broken app without modifying it; produces a structured report
Skill truenas-purge-failed	Clean removal of failed deployments with confirmation gates
Slash /truenas-status	Compact dashboard: system info + all apps
Slash /truenas-list	List apps with optional state filter

The MCP server itself lives in a separate repo (svnstfns/truenas-mcp) so it stays usable from any MCP client (Claude Desktop, Cline, Cursor, …). This plugin is the convenient distribution path for Claude Code users.

Installation

Prerequisites

You need an API key for your TrueNAS. The recommended way is to run the standalone server's interactive installer once — it creates a dedicated mcp-service user with minimal privileges and a user-scoped API key:

uvx --from git+https://github.com/svnstfns/truenas-mcp.git truenas-mcp install

This sets TRUENAS_HOST and TRUENAS_API_KEY in your shell environment (or in ~/.claude.json).

Install the plugin

This repo is a Claude Code marketplace that hosts a single plugin. Install in two steps from a Claude Code session:

/plugin marketplace add svnstfns/truenas-mcp-plugin
/plugin install truenas-mcp@truenas-mcp-plugin

Local development install (after cloning):

/plugin marketplace add /Users/<you>/gh-projects/truenas-mcp-plugin
/plugin install truenas-mcp@truenas-mcp-plugin

Restart the Claude Code session afterward. The truenas MCP server will auto-start, and the three skills + two slash commands will be discoverable.

Verify

In a Claude Code session:

/truenas-status

You should see the system dashboard. If the server can't connect, check that TRUENAS_HOST and TRUENAS_API_KEY are set in your shell.

Configuration

The bundled MCP server reads four environment variables from your shell (or from ~/.claude.json if you ran truenas-mcp install):

Variable	Required	Default	Description
TRUENAS_HOST	yes	nas.pvnkn3t.de	TrueNAS hostname or IP
TRUENAS_API_KEY	yes	—	User-scoped API key
TRUENAS_SSL_VERIFY	no	true	Set false for self-signed certs
MOCK_TRUENAS	no	false	true enables the mock client (for development)

How the pieces fit together

┌────────────────────────────────────────────────────────────────┐
│  Claude Code session                                           │
│                                                                │
│   ┌───────────────────┐    ┌──────────────────────────────┐   │
│   │  Slash commands   │    │           Skills              │   │
│   │  /truenas-status  │    │  truenas-deploy-and-verify    │   │
│   │  /truenas-list    │    │  truenas-troubleshoot         │   │
│   └─────────┬─────────┘    │  truenas-purge-failed         │   │
│             │              └────────────┬──────────────────┘   │
│             └─────────────┬──────────────┘                     │
│                           │                                    │
│                           ▼                                    │
│                ┌──────────────────────┐                        │
│                │  truenas MCP server  │  (uvx, stdio)          │
│                │  15 tools            │                        │
│                └──────────┬───────────┘                        │
└───────────────────────────┼────────────────────────────────────┘
                            │ WebSocket JSON-RPC
                            ▼
              ┌──────────────────────────────┐
              │   TrueNAS Scale 25.04        │
              │   wss://nas.pvnkn3t.de/...   │
              └──────────────────────────────┘

Tools exposed by the bundled MCP server