What can you do with this server?

The TrueNAS Core MCP Server provides a natural language interface to manage and control TrueNAS Core systems through a production-ready Model Context Protocol (MCP) server. User Management: Create, update, delete, and list users with detailed information retrieval and permission management. Storage Management: Manage ZFS pools and datasets with comprehensive capabilities including listing, status checks, property modifications, creating new datasets with compression and quota configuration, and detailed property retrieval. File Sharing: Configure and manage SMB shares, NFS exports with network access and root mapping, and iSCSI targets with defined names, datasets, sizes, and portal IDs for file storage and Kubernetes persistent volumes. Snapshot Management: Create manual snapshots and establish automated snapshot policies with custom schedules, retention settings, and automation for repetitive tasks. Permissions and ACLs: Modify dataset permissions, update Access Control Lists (ACLs), manage Unix permissions, and retrieve detailed permissions information. System Monitoring & Debugging: Check system information, pool health, resource usage, debug connection settings, and reset the HTTP client for maintenance. Integration: Works seamlessly with natural language clients like Claude for easy interaction with TrueNAS systems using both natural language and programmatic interfaces.

Which integrations are available for this server?

Allows interaction with TrueNAS Core systems through the TrueNAS API, enabling management of users, storage (pools and datasets), SMB shares, ZFS snapshots, and retrieving system information.

How do I use TrueNAS Core MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@TrueNAS Core MCP Server list all storage pools and their health status" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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: MCP Tools

📦 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" # 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

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

Debugging API response structure
Accessing fields not included in the formatted response
Troubleshooting integration issues

Tools supporting

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

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