# TrueNAS MCP Server

[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
[![MCP Version](https://img.shields.io/badge/MCP-1.1.0%2B-green)](https://github.com/modelcontextprotocol/python-sdk)
[![License](https://img.shields.io/badge/license-MIT-purple)](LICENSE)
[![PyPI Version](https://img.shields.io/pypi/v/truenas-mcp-server)](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**