← Back to Research Labs

TrueNAS MCP Server

AI-powered automation and management for TrueNAS systems through natural language

Research Preview

Overview

The TrueNAS MCP Server is a Model Context Protocol implementation that enables AI models to manage TrueNAS systems through natural language. This research preview allows you to interact with your TrueNAS storage using AI assistants like Claude, providing comprehensive management capabilities through simple conversational commands.

By leveraging MCP, the server provides a semantic layer on top of the TrueNAS API, allowing AI models to understand storage concepts, make informed decisions, and automate complex storage management tasks. The server runs as a native binary on your desktop and securely connects to your TrueNAS system without requiring any deployment to TrueNAS itself.

⚠️ Research Preview: This project is currently in research preview and is not recommended for production use.

Project Goals

This research project aims to:

  • Enable natural language interaction with TrueNAS systems through AI assistants
  • Automate routine storage management tasks using intelligent agents
  • Provide a standardized interface for third-party integrations
  • Explore use cases for AI-assisted storage operations and troubleshooting
  • Create a foundation for future intelligent storage management features

Core Features

System Monitoring

System information, health status, alerts, and comprehensive performance metrics for CPU, memory, disk I/O, and network.

Storage Management

Pool management, dataset operations, snapshot handling, and file sharing configuration for SMB, NFS, and iSCSI.

Virtual Machines

Complete VM management including creation, configuration, lifecycle control, and resource monitoring.

Directory Services

Integration with Active Directory, LDAP, and FreeIPA for centralized authentication and user management.

Capacity Planning

Utilization analysis, trend forecasting, and intelligent recommendations for storage capacity planning.

System Maintenance

Update management, scrub operations, boot environment control, and automated maintenance tasks.

Application Management

Install, upgrade, and manage TrueNAS applications with task tracking and progress monitoring.

Smart Filtering

Query datasets, snapshots, and VMs with intelligent filters and sorting capabilities.

Safety Features

  • Dry-Run Mode: Preview changes before execution with warnings and estimated execution time
  • Built-in Validation: Prevents dangerous operations with automatic safety checks
  • Task Tracking: Monitor long-running operations with automatic background tracking and progress updates

Technical Architecture

The TrueNAS MCP Server uses a single native binary running on your desktop that connects securely to TrueNAS middleware via WebSocket (wss://). This design requires no deployment to TrueNAS itself, supports self-signed certificates, works cross-platform, and protects API keys through mandatory encryption.

Technology Stack

Model Context Protocol Go Native Binary WebSocket (WSS) TrueNAS Middleware API

Architecture Benefits

  • No TrueNAS Deployment: Runs entirely on your local machine, no installation on TrueNAS required
  • Secure by Default: Enforces encrypted connections (wss://) to protect API keys
  • Cross-Platform: Native binaries available for macOS (ARM/Intel), Linux, and Windows
  • Self-Signed Certificate Support: Works with TrueNAS systems using self-signed certificates
  • Lightweight: Single binary with no runtime dependencies

Security Requirements

🔒 Important: TrueNAS requires encrypted connections (wss://) for API key authentication. Using unencrypted ws:// will cause your API key to be revoked. The MCP server enforces this security measure by default.

Installation

1. Obtain Binary

Download the platform-specific executable from the GitHub releases page:

  • macOS ARM (Apple Silicon)
  • macOS Intel
  • Linux (x86_64)
  • Windows

Place the binary in your system PATH for easy access.

2. Generate API Key

In the TrueNAS web interface:

  1. Navigate to System Settings → API Keys
  2. Click "Add" to create a new API key
  3. Grant appropriate permissions based on your use case
  4. Save the API key securely - you'll need it for configuration

3. Configure MCP Client

Edit your MCP client configuration file (e.g., Claude Desktop, Claude Code) to include: 

{
  "mcpServers": {
    "truenas": {
      "command": "truenas-mcp",
      "args": [
        "--truenas-url", "wss://your-truenas-ip",
        "--api-key", "your-api-key-here"
      ]
    }
  }
}

Alternatively, use environment variables:

  • TRUENAS_URL - Your TrueNAS WebSocket URL
  • TRUENAS_API_KEY - Your API key

4. Restart MCP Client

Restart Claude Desktop or Claude Code to load the MCP server. Once connected, you can start managing your TrueNAS system through natural language commands.

Example Use Cases

Natural language queries and commands you can use with the TrueNAS MCP Server:

System Monitoring

  • "What version of TrueNAS am I running?"
  • "Show me any active alerts on the system"
  • "What's the current CPU and memory usage?"
  • "How much disk space is available?"

Storage Management

  • "What's the health status of my storage pools?"
  • "Show me all datasets and how much space they're using"
  • "List all snapshots on my main pool"
  • "Create a new dataset for video storage with compression enabled"

Maintenance Operations

  • "Are there any system updates available?"
  • "What's the status of the last scrub operation?"
  • "List all boot environments"
  • "When was the last backup completed?"

Application Management

  • "Show me all installed applications"
  • "Upgrade the Plex application"
  • "What's the status of my running apps?"

Advanced Queries

  • "Show me datasets using more than 80% of their quota"
  • "Which VMs are currently running?"
  • "Analyze storage trends over the past month"
  • "Preview creating a new SMB share" (using dry-run mode)

Current Status

Research Preview - Available Now

The TrueNAS MCP Server is currently available as a research preview. While it provides comprehensive functionality across monitoring, storage management, VMs, directory services, capacity planning, maintenance, and application management, it is not yet recommended for production use.

What's Available:

  • ✅ Complete MCP server implementation with native binaries
  • ✅ Full TrueNAS middleware API integration
  • ✅ 8 core feature categories with comprehensive capabilities
  • ✅ Security features including encrypted connections and API key protection
  • ✅ Task tracking for long-running operations
  • ✅ Dry-run mode for safe change previews
  • ✅ Cross-platform support (macOS, Linux, Windows)
  • ✅ Documentation and usage examples

Getting Started: Download the binary from the GitHub repository and follow the installation instructions above.

Get Started Today

The TrueNAS MCP Server is available now as a research preview. Visit the GitHub repository to download the latest release, view the documentation, and join the community.