Truenas Ws

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