Overview

This MCP (Model Context Protocol) server provides a lightweight management layer for TrueNAS Core. It exposes a consistent REST API and helper tools that let developers and operators monitor system health, manage storage and network configuration, and automate backup workflows programmatically. The server acts as an intermediary between client applications and TrueNAS Core, normalizing responses and adding automation primitives such as scheduled tasks, webhooks, and metric exports.

Using an MCP server is useful when you want to centralize TrueNAS automation across multiple systems, integrate with external monitoring or orchestration tools, or provide a simpler API surface for custom tooling. It can be deployed alongside TrueNAS or on a management host and is designed to be integrated into CI/CD pipelines, observability stacks, or admin dashboards.

Features

REST API for common TrueNAS Core operations (pools, datasets, snapshots, network)
Authentication via API tokens and optional TLS support
Scheduling and automation primitives (snapshot rotation, backup jobs)
Metrics export for Prometheus and basic health endpoints
Webhook/event hooks for system events and alerts
Docker-friendly deployment and simple config file (YAML/ENV)
Lightweight CLI client for scripting and one-off tasks

Installation / Configuration

Clone the repository, create a virtual environment, install dependencies, and configure connection details for your TrueNAS systems.

Linux/macOS (virtualenv):

git clone https://github.com/vespo92/TrueNasCoreMCP.git
cd TrueNasCoreMCP
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

Sample configuration file (config.yml):

server:
  host: 0.0.0.0
  port: 8080
  tls:
    enabled: false
    cert_file: /etc/ssl/certs/mcp.crt
    key_file: /etc/ssl/private/mcp.key

truenas:
  - name: truenas-primary
    host: 192.168.1.100
    api_token: "eyJhbGciOi..."
    verify_ssl: true

security:
  admin_api_key: "replace-with-strong-key"
  allowed_ips:
    - "192.168.1.0/24"

Run the server locally:

export MCP_CONFIG=config.yml
python -m truenas_mcp.server

Docker:

# Dockerfile (example)
FROM python:3.11-slim
WORKDIR /app
COPY . /app
RUN pip install -r requirements.txt
ENV MCP_CONFIG=/app/config.yml
CMD ["python", "-m", "truenas_mcp.server"]

Build and run:

docker build -t truenas-mcp .
docker run -d --name truenas-mcp -p 8080:8080 -v /path/to/config.yml:/app/config.yml truenas-mcp

Available Resources

Common REST endpoints (example surface):

Endpoint	Method	Purpose
/api/v1/pools	GET	List storage pools and health
/api/v1/pools/{id}	GET/PUT	Get or modify pool settings
/api/v1/datasets	GET/POST	List or create datasets
/api/v1/snapshots	GET/POST/DELETE	Manage snapshots and retention
/api/v1/network/interfaces	GET/PUT	Inspect and configure interfaces
/api/v1/metrics	GET	Prometheus-style metrics endpoint
/health	GET	Basic server health check

CLI examples:

# List pools
curl -H "Authorization: Bearer $MCP_API_KEY" http://localhost:8080/api/v1/pools

# Create a snapshot (POST body as JSON)
curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MCP_API_KEY" \
  -d '{"dataset":"tank/data","name":"auto-2026-04-10"}' \
  http://localhost:8080/api/v1/snapshots

Use Cases

Centralized monitoring: export pool and disk health metrics to Prometheus using the /api/v1/metrics endpoint, then build Grafana dashboards aggregating multiple TrueNAS hosts.
Automated snapshot rotation: schedule recurring snapshot jobs with retention policies (daily/weekly/monthly) and automatically prune old snapshots via the server’s automation primitives.
Backup orchestration: call dataset snapshot endpoints and then push snapshots or replicated datasets to remote TrueNAS/Cloud targets as part of a CI job.
Network configuration automation: programmatically update VLANs, link aggregation, or interface IPs across multiple systems using a single API request from a deployment script.
Alerting and webhook integrations: register webhooks for low-space or pool-degraded events, then trigger incident workflows in PagerDuty or Slack.

Security and Best Practices

Restrict API access: bind the server to management network interfaces and use firewall rules to limit access.
Use TLS and strong API tokens; rotate tokens periodically.
Run the MCP server close to the TrueNAS instances (same LAN) to reduce latency and secure traffic.
Test automation against a non-production TrueNAS before applying changes to production pools.

For developer integration, use the REST API for programmatic control, or extend the server with additional plugins/hooks to fit custom operational workflows.

TrueNAS Core MCP Server for Management