Skip to main content
Glama
TrueNAS Core MCP Server

TrueNAS Core MCP Server

by vespo92

TrueNAS MCP Server

Python Version MCP Version License PyPI Version

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

Automatic variant detection: The server automatically detects whether you're connected to TrueNAS Core or SCALE and enables the appropriate features.

๐Ÿš€ Features

Universal Features (Core & SCALE)

  • 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

TrueNAS SCALE Features (24.04+)

Automatically enabled when connected to SCALE

  • Apps - Manage Docker Compose-based TrueNAS applications

  • Incus Instances - Control Incus VMs and containers (SCALE 25.04+)

  • Legacy VMs - Manage bhyve virtual machines

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

Related MCP server: truenas-ws-mcp

๐Ÿ“ฆ Installation

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

  1. Log into TrueNAS Web UI

  2. Go to Settings โ†’ API Keys

  3. Click Add and create a new API key

  4. 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"

# TrueNAS SCALE virtualization examples
"List all running apps and their status"
"Get the configuration for the sonarr app"
"Show me all Incus VMs and containers"
"Update the crypto-nodes VM to use 8 CPUs"
"Restart the plex app"

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

File Sharing

  • 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

App Management (TrueNAS SCALE)

  • list_apps - Show all TrueNAS apps with status

  • get_app - Get detailed app information

  • get_app_config - Get full app configuration

  • start_app - Start an app

  • stop_app - Stop an app

  • restart_app - Restart an app

  • redeploy_app - Redeploy after config changes

  • update_app_config - Update app configuration

Incus Instance Management (TrueNAS SCALE)

  • list_instances - Show VMs and containers

  • get_instance - Get instance details

  • start_instance - Start an instance

  • stop_instance - Stop an instance

  • restart_instance - Restart an instance

  • update_instance - Update CPU/memory/autostart

  • list_instance_devices - Show attached devices

Legacy VM Management

  • list_legacy_vms - Show bhyve VMs

  • get_legacy_vm - Get VM details

  • start_legacy_vm - Start a VM

  • stop_legacy_vm - Stop a VM

  • restart_legacy_vm - Restart a VM

  • update_legacy_vm - Update VM configuration

  • get_legacy_vm_status - Get VM status

Debug Tools (Development Mode)

  • debug_connection - Check connection settings

  • test_connection - Verify API connectivity

  • get_server_stats - Server statistics

๐Ÿ“„ Pagination and Response Control

All list operations support pagination to reduce token usage when working with LLM clients. Get operations support optional raw API response inclusion for debugging.

Pagination Parameters

All list_* tools support these parameters:

Parameter

Type

Default

Description

limit

integer

100

Maximum items to return (max: 500)

offset

integer

0

Number of items to skip

Response format:

{
  "success": true,
  "items": [...],
  "metadata": { ... },
  "pagination": {
    "total": 250,
    "limit": 100,
    "offset": 0,
    "returned": 100,
    "has_more": true
  }
}

Usage examples:

"List the first 10 datasets"          โ†’ limit=10
"Show users 50-100"                   โ†’ limit=50, offset=50
"Get all SMB shares (up to 500)"      โ†’ limit=500

Include Raw API Response

Get operations for apps, instances, and VMs support the include_raw parameter:

Parameter

Type

Default

Description

include_raw

boolean

false

Include full API response for debugging

When to use include_raw=true:

  • Debugging API response structure

  • Accessing fields not included in the formatted response

  • Troubleshooting integration issues

Tools supporting include_raw:

  • get_app - App details

  • get_instance - Incus instance details

  • get_legacy_vm - Legacy VM details

Dataset Response Control

The list_datasets and get_dataset tools support an additional parameter:

Parameter

Type

Default

Description

include_children

boolean

true

Include child datasets (can reduce payload significantly)

Usage:

"List only top-level datasets"        โ†’ include_children=false
"Get tank dataset without children"   โ†’ include_children=false

๐Ÿ—๏ธ 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
โ”‚   โ”œโ”€โ”€ app.py           # App models (SCALE)
โ”‚   โ”œโ”€โ”€ instance.py      # Incus instance models (SCALE)
โ”‚   โ””โ”€โ”€ vm.py            # Legacy VM 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
โ”‚   โ”œโ”€โ”€ apps.py          # App tools (SCALE)
โ”‚   โ”œโ”€โ”€ instances.py     # Incus instance tools (SCALE)
โ”‚   โ””โ”€โ”€ vms.py           # Legacy VM 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

๐Ÿค Contributing

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

  1. Fork the repository

  2. Create a feature branch (git checkout -b feature/amazing-feature)

  3. Commit your changes (git commit -m 'Add amazing feature')

  4. Push to the branch (git push origin feature/amazing-feature)

  5. 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

๐Ÿ™ Acknowledgments


Made with โค๏ธ for the TrueNAS community

Available Tools

20 tools
create_datasetB
Create a new dataset

Args:
    pool: Pool name where dataset will be created
    name: Dataset name
    compression: Compression algorithm (default: lz4)
    quota: Optional quota in bytes

Inputs: name (required), pool (required), compression, quota.

create_iscsi_targetB
Create an iSCSI target for Kubernetes block storage

Args:
    name: Target name (e.g., "k8s-block-01")
    dataset: Dataset for storing the iSCSI extent
    size: Size of the iSCSI extent (e.g., "100G")
    portal_id: iSCSI portal ID to use

Inputs: dataset (required), name (required), size (required), portal_id.

create_nfs_exportB
Create an NFS export for Kubernetes persistent volumes

Args:
    dataset: Dataset path to export (e.g., "tank/k8s-volumes")
    allowed_networks: List of allowed networks (e.g., ["10.0.0.0/24"])
    read_only: Whether the export is read-only
    maproot_user: User to map root to
    maproot_group: Group to map root to

Inputs: dataset (required), allowed_networks, maproot_group, maproot_user, +1 more.

create_smb_shareC
Create a new SMB share

Args:
    path: Path to share
    name: Share name
    comment: Optional comment
    read_only: Whether share is read-only

Inputs: name (required), path (required), comment, read_only.

create_snapshotB
Create a snapshot of a dataset

Args:
    dataset: Dataset path (e.g., "tank/data")
    name: Snapshot name
    recursive: Whether to create recursive snapshots

Inputs: dataset (required), name (required), recursive.

create_snapshot_policyB
Create an automated snapshot policy

Args:
    dataset: Dataset to snapshot
    name: Policy name
    schedule: Schedule configuration (cron-like)
             {"minute": "0", "hour": "*/4", "dom": "*", "month": "*", "dow": "*"}
    retention: Retention settings {"hourly": 24, "daily": 7, "weekly": 4, "monthly": 12}
    recursive: Include child datasets

Inputs: dataset (required), name (required), retention (required), schedule (required), +1 more.

debug_connectionB

Debug connection settings and environment variables

Inputs: no named parameters.

get_dataset_permissionsC
Get current permissions and ACL information for a dataset

Args:
    dataset: Dataset path (e.g., "tank/data")

Inputs: dataset (required).

get_dataset_propertiesB
Get all properties of a dataset

Args:
    dataset: Dataset path (e.g., "tank/data")

Inputs: dataset (required).

get_pool_statusC
Get detailed status of a specific pool

Args:
    pool_name: Name of the pool

Inputs: pool_name (required).

get_system_infoB

Get TrueNAS system information

Inputs: no named parameters.

get_userC
Get detailed information about a specific user

Args:
    username: Username to look up

Inputs: username (required).

list_datasetsB

List all datasets

Inputs: no named parameters.

list_poolsB

List all storage pools

Inputs: no named parameters.

list_smb_sharesB

List all SMB shares

Inputs: no named parameters.

list_usersB

List all users in TrueNAS

Inputs: no named parameters.

modify_dataset_permissionsB
Modify dataset permissions (chmod/chown equivalent)

Args:
    dataset: Dataset path (e.g., "tank/data")
    mode: Unix permission mode (e.g., "755", "644")
    owner: Owner username or UID
    group: Group name or GID
    recursive: Apply permissions recursively

Inputs: dataset (required), group, mode, owner, +1 more.

modify_dataset_propertiesB
Modify ZFS dataset properties

Args:
    dataset: Dataset path (e.g., "tank/data")
    properties: Dictionary of properties to update
               Examples: {"compression": "lz4", "dedup": "on", "quota": "10G"}

Inputs: dataset (required), properties (required).

reset_connectionB

Reset the HTTP client to force re-initialization

Inputs: no named parameters.

update_dataset_aclB
Update dataset Access Control Lists (ACLs)

Args:
    dataset: Dataset path (e.g., "tank/data")
    acl_entries: List of ACL entries with permissions
    recursive: Apply ACLs recursively
    strip_acl: Remove all ACLs and revert to Unix permissions

Inputs: acl_entries (required), dataset (required), recursive, strip_acl.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelogโ€ฆ

    TDQS

    B3.4/5.0

    Scored across 20 tools

    Disambiguation4/5

    Most tools have distinct purposes targeting specific TrueNAS resources like datasets, pools, shares, and users, with clear separation between creation, listing, and modification operations. However, some potential overlap exists between 'modify_dataset_permissions' and 'update_dataset_acl' as both handle dataset access control, though their descriptions differentiate Unix permissions versus ACLs.

    Naming Consistency5/5

    Tool names follow a highly consistent verb_noun pattern throughout, such as 'create_dataset', 'list_datasets', 'get_dataset_properties', and 'modify_dataset_permissions'. All tools use snake_case without deviation, making them predictable and readable for an agent.

    Tool Count4/5

    With 20 tools, the count is slightly high but reasonable for a TrueNAS server covering storage management, sharing protocols, and user administration. It includes core operations for datasets, pools, shares, snapshots, and users, though it might benefit from consolidation in areas like debugging tools.

    Completeness4/5

    The tool set provides comprehensive coverage for dataset lifecycle (create, list, get, modify, snapshot), storage pools, and sharing protocols (NFS, SMB, iSCSI), with user management included. Minor gaps exist, such as missing update/delete operations for shares or targets, but agents can likely work around these for core workflows.

    Maintenance

    ActivityInactive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers