vespo92/TrueNasCoreMCP

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
📦 Installation
Quick Start with uvx (Recommended)
The easiest way to run TrueNAS MCP Server is with uvx:
Traditional Installation
From Source
🔧 Configuration
Environment Variables
Create a .env file or set environment variables:
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):
**Note**: This uses uvx to automatically manage the Python environment. Make sure you have uv installed:
📚 Usage Examples
With Claude Desktop
Once configured, you can interact with TrueNAS using natural language:
As a Python Library
Programmatic Usage
🛠️ 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