truenas-ws-mcp 0.1.0

MCP server for TrueNAS Scale — manage storage, apps, VMs, snapshots, and more via the WebSocket API

truenas-ws-mcp

An MCP (Model Context Protocol) server for TrueNAS Scale that connects via the native WebSocket API. Gives AI assistants like Claude full visibility and control over your TrueNAS homelab — storage pools, datasets, apps, VMs, snapshots, SMART tests, and more.

Features

• 61 tools covering storage, apps, VMs, snapshots, sharing, networking, SMART, cloud sync, and system management
• Native WebSocket DDP protocol (same as the TrueNAS UI uses)
• Works with TrueNAS Scale 24.10+ (Dragonfish and newer)
• Runs as a standard MCP server via stdio transport

Quick Start

Install

# With uv (recommended)
uvx truenas-ws-mcp

# With pip
pip install truenas-ws-mcp

Configure

Set these environment variables (or create a .env file):

Variable	Required	Default	Description
TRUENAS_API_KEY	Yes	—	API key from TrueNAS (System > API Keys)
TRUENAS_URL	No	wss://truenas.local/websocket	WebSocket URL of your TrueNAS instance
TRUENAS_VERIFY_SSL	No	false	SSL certificate verification
TRUENAS_TIMEOUT	No	30	API call timeout in seconds

The URL is flexible — you can pass https://192.168.1.100, wss://truenas.local/websocket, or just a hostname. It will be normalized automatically.

Add to Claude Code

{
  "mcpServers": {
    "truenas": {
      "command": "uvx",
      "args": ["truenas-ws-mcp"],
      "env": {
        "TRUENAS_API_KEY": "your-api-key-here",
        "TRUENAS_URL": "wss://your-truenas-ip/websocket"
      }
    }
  }
}

Add to Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "truenas": {
      "command": "uvx",
      "args": ["truenas-ws-mcp"],
      "env": {
        "TRUENAS_API_KEY": "your-api-key-here",
        "TRUENAS_URL": "wss://your-truenas-ip/websocket"
      }
    }
  }
}

Available Tools

Storage (8 tools)

list_pools, get_pool_status, list_datasets, get_dataset, create_dataset, update_dataset, delete_dataset

Snapshots (6 tools)

list_snapshots, create_snapshot, delete_snapshot, rollback_snapshot, clone_snapshot, list_snapshot_tasks

Apps (10 tools)

list_apps, get_app_config, update_app_config, install_app, delete_app, start_app, stop_app, upgrade_app, redeploy_app, list_available_apps

VMs (4 tools)

list_vms, start_vm, stop_vm, update_vm

Sharing (6 tools)

list_smb_shares, create_smb_share, delete_smb_share, list_nfs_exports, create_nfs_export, delete_nfs_export

System (7 tools)

system_info, list_alerts, list_services, list_jobs, get_audit_log, list_cron_jobs, get_boot_pool

Disks & SMART (4 tools)

list_disks, get_disk_temps, list_smart_results, run_smart_test

Network (2 tools)

list_interfaces, get_network_config

Cloud & Replication (4 tools)

list_cloud_syncs, run_cloud_sync, list_replications, run_replication

Reporting (2 tools)

list_graphs, get_reporting_data

Users (5 tools)

list_users, get_user, create_user, update_user, delete_user

Updates & Certs (2 tools)

check_updates, list_certificates

Important Notes

• App config updates are REPLACE, not MERGE. When using update_app_config, send ALL storage/config keys — omitted keys revert to defaults.
• VM RAM/CPU changes require a full stop+start from TrueNAS. Rebooting from inside the VM does NOT re-allocate resources.
• Destructive operations (delete dataset, snapshot, share, user, app) require confirm=True as a safety guard.
• Self-signed certs are common in homelabs. SSL verification is off by default.

Development

git clone https://github.com/thoriphes/truenas-ws-mcp.git
cd truenas-ws-mcp
uv sync
cp env.example .env
# Edit .env with your TrueNAS credentials
uv run pytest

License

MIT