Provides tools for managing TrueNAS Scale systems, including storage pools, datasets, applications, VMs, snapshots, sharing, networking, SMART testing, cloud sync, and system management via the WebSocket API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@truenas-ws-mcp list my storage pools"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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
Related MCP server: TrueNAS Scale MCP Server
# With uv (recommended)
uvx truenas-ws-mcp
# With pip
pip install truenas-ws-mcpSet these environment variables (or create a .env file):
Variable | Required | Default | Description |
| Yes | — | API key from TrueNAS (System > API Keys) |
| No |
| WebSocket URL of your TrueNAS instance |
| No |
| SSL certificate verification |
| No |
| 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.
{
"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 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"
}
}
}
}list_pools, get_pool_status, list_datasets, get_dataset, create_dataset, update_dataset, delete_dataset
list_snapshots, create_snapshot, delete_snapshot, rollback_snapshot, clone_snapshot, list_snapshot_tasks
list_apps, get_app_config, update_app_config, install_app, delete_app, start_app, stop_app, upgrade_app, redeploy_app, list_available_apps
list_vms, start_vm, stop_vm, update_vm
list_smb_shares, create_smb_share, delete_smb_share, list_nfs_exports, create_nfs_export, delete_nfs_export
system_info, list_alerts, list_services, list_jobs, get_audit_log, list_cron_jobs, get_boot_pool
list_disks, get_disk_temps, list_smart_results, run_smart_test
list_interfaces, get_network_config
list_cloud_syncs, run_cloud_sync, list_replications, run_replication
list_graphs, get_reporting_data
list_users, get_user, create_user, update_user, delete_user
check_updates, list_certificates
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.
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 pytestMIT
Check for available TrueNAS system updates.
Inputs: no named parameters. Returns: object
Clone a snapshot to a new dataset.
Inputs: snapshot_name (required), target_dataset (required). Returns: object
Create a new ZFS dataset.
Inputs: name (required), type, compression, quota, +2 more. Returns: object
Create a new NFS export. Path must start with /mnt/.
Inputs: path (required), comment, readonly, networks, +1 more. Returns: object
Create a manual ZFS snapshot.
Inputs: dataset (required), name (required), recursive. Returns: object
Create a new system user.
Inputs: username (required), full_name (required), password (required), email, +2 more. Returns: object
Delete an installed app. Requires confirm=True.
Inputs: app_name (required), confirm. Returns: result
Delete a dataset. Requires confirm=True.
Inputs: name (required), confirm. Returns: result
Delete an NFS export by ID. Requires confirm=True.
Inputs: id (required), confirm. Returns: result
Delete a snapshot. Requires confirm=True. Snapshot format: dataset@name.
Inputs: snapshot_name (required), confirm. Returns: result
Delete a user. Requires confirm=True.
Inputs: user_id (required), confirm. Returns: result
Get the full configuration of a specific app.
Inputs: app_name (required). Returns: object
Query audit log entries (auth events, config changes).
Inputs: services, limit. Returns: result
Get boot pool health status.
Inputs: no named parameters. Returns: object
Get detailed info for a specific dataset.
Inputs: name (required). Returns: object
Get current temperatures for all disks.
Inputs: no named parameters. Returns: result
Get network configuration: DNS servers, gateway, hostname.
Inputs: no named parameters. Returns: object
Get detailed pool status with VDEV topology and error counts.
Inputs: pool_name (required). Returns: object
Get historical reporting data for a graph.
Units: HOUR (1h), DAY (24h), WEEK, MONTH, YEAR. Some graphs need an identifier (e.g., disk name 'sda' for disk graphs, interface name 'enp5s0' for network graphs). Response format: [{name, identifier, data: [[unix_timestamp, value], ...]}]. Memory/ARC values in bytes, CPU in percentage.
Inputs: graph (required), unit, identifier. Returns: result
Get details for a specific user.
Inputs: username (required). Returns: object
Install an app from the catalog.
Inputs: app_name (required), values. Returns: object
List all active TrueNAS alerts with severity levels.
Inputs: no named parameters. Returns: result
List all installed apps with their state.
Inputs: no named parameters. Returns: result
Browse the app catalog for available apps to install.
Inputs: no named parameters. Returns: result
List all SSL/TLS certificates.
Inputs: no named parameters. Returns: result
List all cloud sync tasks with their status and schedule.
Inputs: no named parameters. Returns: result
List all configured cron jobs.
Inputs: no named parameters. Returns: result
List datasets with usage and quota info. Always specify a pool to avoid timeouts on large systems.
Inputs: pool. Returns: result
List all disks with model, serial number, size, and pool membership.
Inputs: no named parameters. Returns: result
List available reporting graphs and their identifiers.
Available graphs include: cpu, cputemp, memory, disk, interface, load, uptime, arcsize, disktemp, and more. Some graphs require an identifier (disk name for 'disk'/'disktemp', interface name for 'interface').
Inputs: no named parameters. Returns: result
List network interfaces with IPs and link state.
Inputs: no named parameters. Returns: result
List recent system jobs with status, progress, and errors.
Inputs: no named parameters. Returns: result
List all NFS exports.
Inputs: no named parameters. Returns: result
List all storage pools with health, capacity, and fragmentation.
Inputs: no named parameters. Returns: result
List all replication tasks with their status.
Inputs: no named parameters. Returns: result
List all services and their running status (SMB, NFS, SSH, etc.).
Inputs: no named parameters. Returns: result
List SMART test results for all disks.
Inputs: no named parameters. Returns: result
List ZFS snapshots. Always specify a dataset to avoid timeouts on large systems.
Inputs: dataset. Returns: result
List automated snapshot task schedules.
Inputs: no named parameters. Returns: result
List all system users.
Inputs: no named parameters. Returns: result
List all virtual machines with their state, CPU, and RAM configuration.
Inputs: no named parameters. Returns: result
Redeploy an app with its current configuration.
Inputs: app_name (required). Returns: result
Rollback dataset to snapshot. Requires confirm=True. WARNING: destroys newer data.
Inputs: snapshot_name (required), confirm. Returns: result
Trigger a cloud sync task to run immediately.
Inputs: task_id (required). Returns: result
Trigger a replication task to run immediately.
Inputs: task_id (required). Returns: result
Run a SMART test on specified disks. test_type: SHORT or LONG. Note: TrueNAS 25.10 removed SMART scheduling from the API — these are manual tests only.
Inputs: disks (required), test_type. Returns: result
Start a stopped app.
Inputs: app_name (required). Returns: result
Start a virtual machine.
Inputs: vm_id (required). Returns: result
Stop a running app.
Inputs: app_name (required). Returns: result
Stop a virtual machine. Attempts graceful shutdown first, forces after timeout.
RAM/CPU changes require full stop+start from TrueNAS — in-guest reboot does NOT re-allocate resources.
Inputs: vm_id (required), force. Returns: result
Get TrueNAS system information: version, uptime, CPU, RAM, boot time.
Inputs: no named parameters. Returns: object
Update app configuration.
WARNING: This is a REPLACE operation, not a merge. Any config keys not included will revert to defaults. Always get current config first with get_app_config, modify the needed values, and send the complete config.
Inputs: app_name (required), values (required). Returns: object
Update dataset properties (compression, quota, comments, etc.).
Inputs: name (required), properties (required). Returns: object
Update user properties.
Inputs: user_id (required), properties (required). Returns: object
Update VM configuration (RAM, CPUs, etc.).
Note: RAM/CPU changes only take effect after a full stop+start from TrueNAS — rebooting from inside the VM does NOT re-allocate resources.
Inputs: vm_id (required), settings (required). Returns: object
Upgrade an app to the latest available version.
Inputs: app_name (required). Returns: object
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 59 tools
Each tool targets a distinct resource and action (e.g., create_dataset vs delete_dataset, list_apps vs list_available_apps). Descriptions clearly differentiate similar tools, and overlaps are minimal and well-explained.
The vast majority use a consistent verb_noun pattern in snake_case (e.g., create_dataset, delete_user). The only minor exception is 'system_info' (noun_noun), but overall the naming is predictable and easy to follow.
With 59 tools, the count is excessively high for an MCP server, far beyond the typical 3-15 range. While TrueNAS is a complex system, many tools could be consolidated (e.g., separate list/get tools could be combined with parameters).
The tool set heavily favors read operations (list/get), but lacks write/update/delete for many key resources such as services, certificates, cron jobs, replication tasks, cloud sync tasks, and network configuration. This leaves significant gaps for full system management.
MCP server for Gainium — manage trading bots, deals, and balances via AI assistants
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
