TrueNAS Core MCP

What is TrueNAS Core MCP?

TrueNAS Core MCP is a server that facilitates natural language interaction with your TrueNAS Core system. It acts as a bridge between AI clients like Claude Desktop and your TrueNAS server, allowing you to manage various aspects of your TrueNAS system using simple, conversational commands.

How to use TrueNAS Core MCP?

To use TrueNAS Core MCP, you need Python 3.10+, a TrueNAS Core system with API access, Claude Desktop (or any MCP-compatible client), and a TrueNAS API key. After cloning the repository, you can use the quick_setup.sh script or manually set up a Python virtual environment and install dependencies. Configure the .env file with your TrueNAS URL and API key. Finally, configure Claude Desktop to include the TrueNAS MCP server, and you can start issuing natural language commands.

Key Features of TrueNAS Core MCP

Storage Management: Create and manage pools, datasets, and snapshots.
User Administration: List, view, and manage system users.
Advanced Permissions: Control Unix permissions and ACLs.
Kubernetes Ready: Export NFS shares and create iSCSI targets for Kubernetes.
Automation: Set up automated snapshot policies and retention.
Property Control: Manage ZFS properties like compression, deduplication, and quotas.

Use Cases of TrueNAS Core MCP

Simplified TrueNAS Management: Control your TrueNAS system using natural language, eliminating the need for complex command-line interfaces.
Automated Tasks: Set up automated snapshot policies for data protection.
Kubernetes Integration: Easily provision storage for Kubernetes clusters.
User and Permission Management: Efficiently manage users and their access rights on your TrueNAS system.

FAQ from TrueNAS Core MCP

Q: What are the prerequisites for running TrueNAS Core MCP? A: You need Python 3.10 or higher, a TrueNAS Core system with API access, Claude Desktop (or any MCP-compatible client), and a TrueNAS API key.

Q: How do I get my TrueNAS API key? A: Log into your TrueNAS web interface, navigate to Settings → API Keys, click Add, name your key, and copy the generated key.

Q: Can I use TrueNAS Core MCP with other MCP-compatible clients besides Claude Desktop? A: Yes, TrueNAS Core MCP is designed to work with any MCP client.

Q: What kind of commands can I issue to TrueNAS Core MCP? A: You can issue natural language commands for basic operations like listing users and pools, creating datasets, and advanced features like setting permissions, enabling compression, and creating NFS exports for Kubernetes.

TrueNAS MCP Server

Control your TrueNAS system using natural language through Claude Desktop

Features • Quick Start • Installation • Documentation • Examples

🌟 Overview

TrueNAS MCP Server enables seamless interaction between Claude Desktop (or any MCP client) and your TrueNAS Core system. Manage storage, users, permissions, and even Kubernetes storage backends—all through natural language commands.

🎯 Key Features

🗂️ Storage Management - Create and manage pools, datasets, and snapshots
👥 User Administration - List, view, and manage system users
🔐 Advanced Permissions - Control Unix permissions and ACLs with simple commands
☸️ Kubernetes Ready - Export NFS shares and create iSCSI targets for K8s
🤖 Automation - Set up automated snapshot policies and retention
📊 Property Control - Manage ZFS properties like compression, deduplication, and quotas

✅ Tested On

TrueNAS Core: Version 13.0-U6.1
API Version: v2.0
Python: 3.10+

🚀 Quick Start

Prerequisites

Python 3.10 or higher
TrueNAS Core system with API access
Claude Desktop (or any MCP-compatible client)
TrueNAS API key

1. Clone & Install

# Clone the repository
git clone https://github.com/vespo92/TrueNasCoreMCP.git
cd TrueNasCoreMCP

# Quick setup (recommended)
./quick_setup.sh  # On Windows: quick_setup.bat

# Or manual setup:
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

2. Configure

# Copy example config
cp .env.example .env

# Edit with your TrueNAS details
nano .env

Set your TrueNAS connection details:

TRUENAS_URL=https://192.168.1.100
TRUENAS_API_KEY=1-your-api-key-here
TRUENAS_VERIFY_SSL=false

3. Test Connection

python tests/test_connection.py

4. Configure Claude Desktop

Add to your Claude Desktop config:

{
  "mcpServers": {
    "truenas": {
      "command": "python",
      "args": ["/path/to/truenas_mcp_server.py"],
      "env": {
        "TRUENAS_URL": "https://your-truenas-ip",
        "TRUENAS_API_KEY": "your-api-key",
        "TRUENAS_VERIFY_SSL": "false"
      }
    }
  }
}

📚 Documentation

Getting Your API Key

Log into TrueNAS web interface
Navigate to Settings → API Keys
Click Add and name your key
Copy the generated key immediately

Example Commands

Once configured, ask Claude natural language questions:

Basic Operations

"List all users in my TrueNAS"
"Show me the storage pools"
"Create a dataset called backups in the tank pool"
"Take a snapshot of tank/important"

Advanced Features

"Set permissions 755 on tank/shared with owner john"
"Enable compression on tank/backups"
"Create an NFS export for my Kubernetes cluster"
"Set up daily snapshots for tank/data with 30-day retention"

Detailed Documentation

🛠️ Available Functions

list_pools() - View all storage pools
list_datasets() - List all datasets
get_pool_status() - Detailed pool information
create_dataset() - Create new datasets
modify_dataset_properties() - Change ZFS properties
get_dataset_properties() - View dataset configuration

list_users() - List system users
get_user() - Detailed user information
modify_dataset_permissions() - Change Unix permissions
update_dataset_acl() - Manage Access Control Lists
get_dataset_permissions() - View current permissions

list_smb_shares() - View SMB/CIFS shares
create_smb_share() - Create new SMB shares
create_nfs_export() - NFS exports for Kubernetes
create_iscsi_target() - iSCSI block storage

create_snapshot() - Manual snapshots
create_snapshot_policy() - Automated snapshot schedules

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
pytest tests/

# Format code
black truenas_mcp_server.py

# Lint
flake8 truenas_mcp_server.py

🔒 Security

API keys are stored securely in environment variables
SSL/TLS verification is configurable
Never commit .env files or API keys
See Security Policy for reporting vulnerabilities

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built for TrueNAS Core
Powered by Model Context Protocol (MCP)
Uses FastMCP for easy server creation
Tested on TrueNAS-13.0-U6.1

TrueNAS Core MCP Overview