TrueNAS Scale MCP Server

A Model Context Protocol (MCP) server for managing TrueNAS Scale Custom Apps through Docker-based deployments.

Overview

This MCP server enables AI assistants like Claude to manage TrueNAS Scale Custom Apps using natural language commands. It provides tools for deploying, managing, and monitoring Docker Compose applications on TrueNAS Scale systems.

Features

• 11 MCP Tools for comprehensive Custom App management
• Docker Compose Conversion to TrueNAS Custom App format
• Security Validation with input sanitization
• Mock Development Mode for testing without TrueNAS access
• Comprehensive Test Suite with >80% coverage
• WebSocket API Integration with TrueNAS Electric Eel

Quick Start

Prerequisites

• Python 3.10+
• Poetry for dependency management
• TrueNAS Scale 24.10+ (Electric Eel) with API access

Installation

# Clone the repository
git clone https://github.com/yourusername/truenas-mcp-server.git
cd truenas-mcp-server

# Install dependencies
poetry install

# Install pre-commit hooks (optional)
poetry run pre-commit install

Configuration

Set up environment variables for your TrueNAS system:

export TRUENAS_HOST="nas.pvnkn3t.lan"
export TRUENAS_API_KEY="your-api-key-here"
export TRUENAS_PORT="443"
export TRUENAS_PROTOCOL="wss"
export TRUENAS_SSL_VERIFY="false"  # Use "true" for production
export DEBUG_MODE="false"

Testing the Server

# Test with mock TrueNAS (no real TrueNAS required)
MOCK_TRUENAS=true poetry run python src/truenas_mcp/mcp_server.py

# Test with real TrueNAS
poetry run python src/truenas_mcp/mcp_server.py

Claude Code Integration

Add this server to your Claude Code MCP configuration:

Option 1: Direct Python Execution

Add to your ~/.claude/mcp-servers/production.json:

{
  "mcpServers": {
    "truenas-scale": {
      "type": "stdio",
      "command": "python",
      "args": ["/path/to/truenas-mcp-server/src/truenas_mcp/mcp_server.py"],
      "env": {
        "TRUENAS_HOST": "nas.pvnkn3t.lan",
        "TRUENAS_API_KEY": "your-api-key-here",
        "TRUENAS_PORT": "443",
        "TRUENAS_PROTOCOL": "wss",
        "TRUENAS_SSL_VERIFY": "false"
      }
    }
  }
}

Option 2: Poetry Execution

{
  "mcpServers": {
    "truenas-scale": {
      "type": "stdio",
      "command": "poetry",
      "args": ["run", "python", "src/truenas_mcp/mcp_server.py"],
      "cwd": "/path/to/truenas-mcp-server",
      "env": {
        "TRUENAS_HOST": "nas.pvnkn3t.lan",
        "TRUENAS_API_KEY": "your-api-key-here",
        "TRUENAS_PORT": "443",
        "TRUENAS_PROTOCOL": "wss",
        "TRUENAS_SSL_VERIFY": "false"
      }
    }
  }
}

Usage Examples

Once configured, you can use these natural language commands with Claude:

# List all Custom Apps
claude "List all my TrueNAS Custom Apps and their status"

# Deploy a new app