TrueNAS Core MCP Server

# TrueNAS MCP Server [](https://www.python.org/downloads/) [](https://github.com/modelcontextprotocol/python-sdk) [](LICENSE) [](https://pypi.org/project/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](https://github.com/astral-sh/uv): ```bash # Run directly without installation uvx truenas-mcp-server # Or install globally with uv uv tool install truenas-mcp-server ``` ### Traditional Installation ```bash # With pip pip install truenas-mcp-server # Or with pipx for isolated environment pipx install truenas-mcp-server ``` ### From Source ```bash git clone https://github.com/vespo92/TrueNasCoreMCP.git cd TrueNasCoreMCP pip install -e . ``` ## 🔧 Configuration ### Environment Variables Create a `.env` file or set environment variables: ```bash # 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`): ```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](https://github.com/astral-sh/uv) installed: ```bash # 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 ```python from truenas_mcp_server import TrueNASMCPServer # Create server instance server = TrueNASMCPServer() # Run the server server.run() ``` ### Programmatic Usage ```python 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:** ```json { "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 ```bash # 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 ```bash # Run all tests pytest # With coverage pytest --cov=truenas_mcp_server # Specific test file pytest tests/test_client.py ``` ### Code Quality ```bash # Format code black truenas_mcp_server # Lint flake8 truenas_mcp_server # Type checking mypy truenas_mcp_server ``` ## 📖 Documentation - [Installation Guide](docs/guides/INSTALL.md) - Detailed installation instructions - [Quick Start](docs/guides/QUICKSTART.md) - Get up and running quickly - [Quick Reference](docs/guides/QUICK_REFERENCE.md) - Command reference - [Features Overview](docs/guides/FEATURES.md) - Detailed feature documentation - [API Documentation](docs/api/) - Coming soon ## 🤝 Contributing Contributions are welcome! Please see [CONTRIBUTING.md](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](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](https://github.com/vespo92/TrueNasCoreMCP/issues) - **Discussions**: [GitHub Discussions](https://github.com/vespo92/TrueNasCoreMCP/discussions) ## 🙏 Acknowledgments - [Anthropic](https://www.anthropic.com/) for the MCP specification - [TrueNAS](https://www.truenas.com/) for the excellent storage platform - [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) contributors --- **Made with ❤️ for the TrueNAS community**