TrueNAS

You can control and automate your TrueNAS infrastructure using the MCP server, which exposes storage, user, sharing, and virtualization management through an MCP client. This server automatically detects whether you’re connected to TrueNAS Core or SCALE and enables the appropriate features, providing secure, typed operations with robust logging and error handling.

How to use

You interact with the MCP server through an MCP client by issuing natural language commands or programmatic API calls. Start by authenticating to your TrueNAS instance via the API key and URL you configure, then perform operations such as managing users, storage pools, datasets, and shares, or controlling apps and virtual instances when connected to SCALE. The server presents structured responses and clear error messages to guide you through failures or partial successes.

How to install

Prerequisites: You need Python installed on the host that will run the MCP server, and you may choose a local environment manager such as uvx for streamlined runtimes.

# Quick start using uvx (recommended)
uvx truenas-mcp-server

# Or install globally with uv
uv tool install truenas-mcp-server
```}]} ,{

Configuration and usage notes

Configure access to your TrueNAS instance by setting environment variables that you will reference when starting the MCP server. Required values include the TrueNAS URL and API key, with optional SSL verification, logging level, environment, and timeouts. You can place these in a .env file or export them in your shell before launching the server.

Key environment variables to set are:

• TRUENAS_URL: The base URL of your TrueNAS API endpoint
• TRUENAS_API_KEY: The API key generated from your TrueNAS UI Optional:
• TRUENAS_VERIFY_SSL: false to skip SSL verification in development environments
• TRUENAS_LOG_LEVEL: INFO (or DEBUG, WARN, ERROR)
• TRUENAS_ENV: development, staging, or production
• TRUENAS_HTTP_TIMEOUT: HTTP timeout seconds
• TRUENAS_ENABLE_DESTRUCTIVE_OPS: false to restrict delete operations
• TRUENAS_ENABLE_DEBUG_TOOLS: false to disable debug tooling

Security and maintenance

Protect your credentials by not committing API keys or tokens. Use SSL verification in production, and restrict destructive operations by default. Regularly rotate API keys and monitor access logs to detect unauthorized usage.

Usage examples

Use natural language or programmatic calls to perform tasks such as creating users, managing pools and datasets, configuring file shares, or deploying apps and VMs on SCALE. For example, you can request listing pools, creating a new dataset, or setting up a new SMB share, and you will receive structured responses that indicate success or detail any errors.

Troubleshooting

If you encounter connectivity or permission issues, verify that TRUENAS_URL and TRUENAS_API_KEY are correct and that SSL verification is configured appropriately. Check the server logs for error messages, ensure the API key has the necessary permissions, and confirm that the MCP server can reach the TrueNAS API endpoint.

Available tools

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

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

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

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

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

list_instances

Show Incus 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

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