TrueNAS MCP Server
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:
# 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 detailsget_user- Get specific user informationcreate_user- Create new user accountupdate_user- Modify user propertiesdelete_user- Remove user account
Storage Management
list_pools- Show all storage poolsget_pool_status- Detailed pool health and statisticslist_datasets- List all datasetscreate_dataset- Create new dataset with optionsupdate_dataset- Modify dataset propertiesdelete_dataset- Remove dataset
File Sharing
list_smb_shares- Show SMB/CIFS sharescreate_smb_share- Create Windows sharelist_nfs_exports- Show NFS exportscreate_nfs_export- Create NFS exportlist_iscsi_targets- Show iSCSI targetscreate_iscsi_target- Create iSCSI target
Snapshot Management
list_snapshots- Show snapshotscreate_snapshot- Create manual snapshotdelete_snapshot- Remove snapshotrollback_snapshot- Revert to snapshotclone_snapshot- Clone to new datasetcreate_snapshot_task- Setup automated snapshots
App Management (TrueNAS SCALE)
list_apps- Show all TrueNAS apps with statusget_app- Get detailed app informationget_app_config- Get full app configurationstart_app- Start an appstop_app- Stop an apprestart_app- Restart an appredeploy_app- Redeploy after config changesupdate_app_config- Update app configuration
Incus Instance Management (TrueNAS SCALE)
list_instances- Show VMs and containersget_instance- Get instance detailsstart_instance- Start an instancestop_instance- Stop an instancerestart_instance- Restart an instanceupdate_instance- Update CPU/memory/autostartlist_instance_devices- Show attached devices
Legacy VM Management
list_legacy_vms- Show bhyve VMsget_legacy_vm- Get VM detailsstart_legacy_vm- Start a VMstop_legacy_vm- Stop a VMrestart_legacy_vm- Restart a VMupdate_legacy_vm- Update VM configurationget_legacy_vm_status- Get VM status
Debug Tools (Development Mode)
debug_connection- Check connection settingstest_connection- Verify API connectivityget_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 detailsget_instance- Incus instance detailsget_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