-
securityF
license-
qualityA Model Context Protocol server built with mcp-framework that allows users to create and manage custom tools for processing data, integrating with the Claude Desktop via CLI.
Last updated -
14
5
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.
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.
TrueNAS MCP Server
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 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
Debug Tools (Development Mode)
debug_connection- Check connection settingstest_connection- Verify API connectivityget_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
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Tools
A Model Context Protocol server that enables Claude Desktop and other MCP clients to interact with TrueNAS Core systems through the TrueNAS API, supporting user management, storage operations, sharing, and snapshot creation.
Related MCP Servers
- -securityAlicense-qualityA custom Model Context Protocol server that gives Claude Desktop and other LLMs access to file system operations and command execution capabilities through standardized tool interfaces.Last updated -24Apache 2.0
- -securityFlicense-qualityA filesystem Model Context Protocol server that provides Claude Desktop with capabilities to read, write, and manipulate files on your system.Last updated -0
- -securityFlicense-qualityIntegration project for Model Context Protocol (MCP) servers with Claude Desktop App, enabling filesystem operations, development support, and file management through natural language.Last updated -