Skip to main content
Glama

TrueNAS Core MCP Server

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

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

  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):

{ "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 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

Debug Tools (Development Mode)

  • debug_connection - Check connection settings
  • test_connection - Verify API connectivity
  • get_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

🤝 Contributing

Contributions are welcome! Please see 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 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

🙏 Acknowledgments


Made with ❤️ for the TrueNAS community

Related MCP Servers

  • -
    security
    F
    license
    -
    quality
    A 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 -
    26
    5
    • Apple
  • -
    security
    A
    license
    -
    quality
    A 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 -
    24
    Apache 2.0
    • Apple
    • Linux
  • -
    security
    F
    license
    -
    quality
    A filesystem Model Context Protocol server that provides Claude Desktop with capabilities to read, write, and manipulate files on your system.
    Last updated -
    4
  • -
    security
    F
    license
    -
    quality
    Integration project for Model Context Protocol (MCP) servers with Claude Desktop App, enabling filesystem operations, development support, and file management through natural language.
    Last updated -

View all related MCP servers

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/vespo92/TrueNasCoreMCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server