TrueNAS MCP Server

What is TrueNAS MCP Server about?

Enables control of TrueNAS Core systems through natural language commands, exposing the full set of storage‑related actions (users, pools, datasets, shares, snapshots) via the Model Context Protocol.

How to use TrueNAS MCP Server?

Install – preferred method is with uvx:
```
uvx truenas-mcp-server
```
or install globally with uv tool install truenas-mcp-server, pip install truenas-mcp-server, or pipx install truenas-mcp-server.
Configure – create a .env file (or set environment variables) with the required keys:
```
TRUENAS_URL=https://your-truenas-server.local
TRUENAS_API_KEY=your-api-key-here
```
Optional settings control SSL verification, log level, timeouts, and destructive‑operation toggles.
Run – start the server (e.g., uvx truenas-mcp-server).
Connect – add the server to Claude Desktop or any MCP‑compatible client using the command and environment variables defined during installation.

Key features of TrueNAS MCP Server

User Management – create, update, delete users and handle permissions.
Storage Management – full ZFS pool and dataset operations.
File Sharing – configure SMB, NFS, and iSCSI shares.
Snapshot Management – create, delete, rollback, clone, and schedule snapshots.
System Monitoring – health checks, resource usage, and pool status.
Type‑Safe Pydantic models for request/response validation.
Robust error handling with detailed messages.
Structured logging with configurable levels.
Connection pooling and retry logic for reliable HTTP calls.
Rate limiting to protect the API.
Environment‑based configuration using .env or OS variables.

Use cases of TrueNAS MCP Server

Ops automation – script routine storage tasks (e.g., daily snapshot creation) via natural‑language prompts.
Self‑service portal – allow non‑technical staff to request new shares or datasets through chat interfaces.
Compliance enforcement – enable/disable destructive operations per environment to prevent accidental data loss.
Monitoring dashboards – integrate with observability tools to surface health metrics retrieved via MCP.
CI/CD pipelines – provision temporary datasets for testing and tear them down automatically.

FAQ from the TrueNAS MCP Server

Q: Do I need to expose my TrueNAS API key publicly? A: No. Store the key in environment variables or a .env file; never commit it to source control.

Q: Can I run the server on Windows? A: Yes, as long as Python 3.10+ is installed. Use the same uvx/pip commands in a PowerShell or CMD session.

Q: How do I enable destructive operations like delete? A: Set TRUENAS_ENABLE_DESTRUCTIVE_OPS=true in your environment. It defaults to false for safety.

Q: Is TLS verification required? A: In production you should keep TRUENAS_VERIFY_SSL=true. For local testing you can disable it with false.

Q: What clients can talk to this server? A: Any MCP‑compatible client, such as Claude Desktop, custom Python scripts using the provided SDK, or other language bindings.

A production-ready Model Context Protocol (MCP) server for TrueNAS Core systems. Control and manage your TrueNAS storage through natural language with Claude or other MCP-compatible clients.

🚀 Features

Core Capabilities

User Management - Create, update, delete users and manage permissions
Storage Management - Manage pools, datasets, volumes with full ZFS support
File Sharing - Configure SMB, NFS, and iSCSI shares
Snapshot Management - Create, delete, rollback snapshots with automation
System Monitoring - Check system health, pool status, and resource usage

Enterprise Features

Type-Safe Operations - Full Pydantic models for request/response validation
Comprehensive Error Handling - Detailed error messages and recovery guidance
Production Logging - Structured logging with configurable levels
Connection Pooling - Efficient HTTP connection management with retry logic
Rate Limiting - Built-in rate limiting to prevent API abuse
Environment-Based Config - Flexible configuration via environment variables

📦 Installation

Quick Start with uvx (Recommended)

The easiest way to run TrueNAS MCP Server is with uvx:

# Run directly without installation
uvx truenas-mcp-server

# Or install globally with uv
uv tool install truenas-mcp-server

Traditional Installation

# With pip
pip install truenas-mcp-server

# Or with pipx for isolated environment
pipx install truenas-mcp-server

From Source

git clone https://github.com/vespo92/TrueNasCoreMCP.git
cd TrueNasCoreMCP
pip install -e .

🔧 Configuration

Environment Variables

Create a .env file or set environment variables:

# Required
TRUENAS_URL=https://your-truenas-server.local
TRUENAS_API_KEY=your-api-key-here

# Optional
TRUENAS_VERIFY_SSL=true                    # Verify SSL certificates
TRUENAS_LOG_LEVEL=INFO                     # Logging level
TRUENAS_ENV=production                     # Environment (development/staging/production)
TRUENAS_HTTP_TIMEOUT=30                    # HTTP timeout in seconds
TRUENAS_ENABLE_DESTRUCTIVE_OPS=false      # Enable delete operations
TRUENAS_ENABLE_DEBUG_TOOLS=false          # Enable debug tools

Getting Your API Key

Log into TrueNAS Web UI
Go to Settings → API Keys
Click Add and create a new API key
Copy the key immediately (it won't be shown again)

Claude Desktop Configuration

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "truenas": {
      "command": "uvx",
      "args": ["truenas-mcp-server"],
      "env": {
        "TRUENAS_URL": "https://your-truenas-server.local",
        "TRUENAS_API_KEY": "your-api-key-here",
        "TRUENAS_VERIFY_SSL": "false"
      }
    }
  }
}

Note: This uses uvx to automatically manage the Python environment. Make sure you have uv installed:

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh
# or
brew install uv

📚 Usage Examples

With Claude Desktop

Once configured, you can interact with TrueNAS using natural language:

"List all storage pools and their health status"
"Create a new dataset called 'backups' in the tank pool with compression"
"Set up an SMB share for the documents dataset"
"Create a snapshot of all datasets in the tank pool"
"Show me users who have sudo privileges"

As a Python Library

from truenas_mcp_server import TrueNASMCPServer

# Create server instance
server = TrueNASMCPServer()

# Run the server
server.run()

Programmatic Usage

import asyncio
from truenas_mcp_server.client import TrueNASClient
from truenas_mcp_server.config import Settings

async def main():
    # Initialize client
    settings = Settings(
        truenas_url="https://truenas.local",
        truenas_api_key="your-api-key"
    )
    
    async with TrueNASClient(settings) as client:
        # List pools
        pools = await client.get("/pool")
        print(f"Found {len(pools)} pools")
        
        # Create a dataset
        dataset = await client.post("/pool/dataset", {
            "name": "tank/mydata",
            "compression": "lz4"
        })
        print(f"Created dataset: {dataset['name']}")

asyncio.run(main())

🛠️ Available Tools

User Management

list_users - List all users with details
get_user - Get specific user information
create_user - Create new user account
update_user - Modify user properties
delete_user - Remove user account

Storage Management

list_pools - Show all storage pools
get_pool_status - Detailed pool health and statistics
list_datasets - List all datasets
create_dataset - Create new dataset with options
update_dataset - Modify dataset properties
delete_dataset - Remove dataset

list_smb_shares - Show SMB/CIFS shares
create_smb_share - Create Windows share
list_nfs_exports - Show NFS exports
create_nfs_export - Create NFS export
list_iscsi_targets - Show iSCSI targets
create_iscsi_target - Create iSCSI target

Snapshot Management

list_snapshots - Show snapshots
create_snapshot - Create manual snapshot
delete_snapshot - Remove snapshot
rollback_snapshot - Revert to snapshot
clone_snapshot - Clone to new dataset
create_snapshot_task - Setup automated snapshots

Debug Tools (Development Mode)

debug_connection - Check connection settings
test_connection - Verify API connectivity
get_server_stats - Server statistics

🏗️ Architecture

truenas_mcp_server/
├── __init__.py           # Package initialization
├── server.py             # Main MCP server
├── config/               # Configuration management
│   ├── __init__.py
│   └── settings.py       # Pydantic settings
├── client/               # HTTP client
│   ├── __init__.py
│   └── http_client.py    # Async HTTP with retry
├── models/               # Data models
│   ├── __init__.py
│   ├── base.py          # Base models
│   ├── user.py          # User models
│   ├── storage.py       # Storage models
│   └── sharing.py       # Share models
├── tools/                # MCP tools
│   ├── __init__.py
│   ├── base.py          # Base tool class
│   ├── users.py         # User tools
│   ├── storage.py       # Storage tools
│   ├── sharing.py       # Share tools
│   └── snapshots.py     # Snapshot tools
└── exceptions.py         # Custom exceptions

🧪 Development

Setup Development Environment

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

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

Running Tests

# Run all tests
pytest

# With coverage
pytest --cov=truenas_mcp_server

# Specific test file
pytest tests/test_client.py

Code Quality

# Format code
black truenas_mcp_server

# Lint
flake8 truenas_mcp_server

# Type checking
mypy truenas_mcp_server

📖 Documentation

Installation Guide - Detailed installation instructions
Quick Start - Get up and running quickly
Quick Reference - Command reference
Features Overview - Detailed feature documentation
API Documentation - Coming soon

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📝 License

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

🔒 Security

Never commit API keys or credentials
Use environment variables for sensitive data
Enable SSL verification in production
Restrict destructive operations by default
Report security issues via GitHub Issues

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions

🙏 Acknowledgments

Anthropic for the MCP specification
TrueNAS for the excellent storage platform
MCP Python SDK contributors

Made with ❤️ for the TrueNAS community

TrueNAS MCP Server