TrueNAS MCP Server

Read-only MCP server for TrueNAS Scale debugging. Runs directly on TrueNAS and provides:

• k3s tools — kubectl get/describe/logs/events/top wrapped as MCP tools
• TrueNAS API — whitelisted midclt call methods for system info, apps, pools

No destructive operations. Every tool is read-only.

Quick Start

# Install
pip install git+https://github.com/a-simple-test-organization/truenas-mcp.git

# Run (no auth)
MCP_PORT=38888 python -m truenas_mcp.server
# Starts on http://0.0.0.0:38888/mcp

# Health check
curl http://localhost:38888/health
# → {"status": "ok", "auth_enabled": false}

Authentication

Set MCP_TOKEN to enable Bearer token auth. Then all requests must include Authorization: Bearer <token>.

# Generate a token
openssl rand -hex 32

# Run with auth
MCP_TOKEN="your-token-here" MCP_PORT=38888 python -m truenas_mcp.server

Client configuration (e.g. OpenClaw, Claude Code, OpenCode):

{
  "mcpServers": {
    "truenas": {
      "url": "http://192.168.2.48:38888/mcp",
      "headers": {
        "Authorization": "Bearer your-token-here"
      }
    }
  }
}

The /health endpoint is always available without authentication.

systemd Deployment

# Copy the unit file
cp deploy/truenas-mcp.service /etc/systemd/system/

# Edit Environment=MCP_TOKEN= to set your token
vim /etc/systemd/system/truenas-mcp.service

# Enable and start
systemctl daemon-reload
systemctl enable --now truenas-mcp.service

# Check
systemctl status truenas-mcp
journalctl -u truenas-mcp -f

MCP Tools

k3s (9 tools)

Tool	Description
kubectl_get	Get resources (pods, deployments, nodes, ...)
kubectl_describe	Detailed resource description
kubectl_logs	Container logs
kubectl_events	Cluster events
kubectl_nodes	Node status
kubectl_top_pods	Resource usage by pod
kubectl_top_nodes	Resource usage by node
kubectl_api_resources	Available API types
pod_status_summary	Quick all-pods overview

TrueNAS (2 tools)

Tool	Description
midclt_call	Call whitelisted TrueNAS API method
midclt_call_arg	Call with arguments

Debugging Slow App Startup

1. pod_status_summary
2. kubectl_events(all_namespaces=True)
3. kubectl_describe(resource_type="pod", name="<slow-pod>", namespace="ix-<app>")
4. kubectl_logs(pod_name="<slow-pod>", namespace="ix-<app>")
5. midclt_call(method="chart.release.query")

Environment Variables

Variable	Default	Description
K3S_BIN	auto (PATH + fallbacks)	Path to k3s binary
MIDCLT_BIN	auto (PATH + fallbacks)	Path to midclt binary
MCP_PORT	8000	HTTP listen port
MCP_HOST	0.0.0.0	HTTP listen host
MCP_PATH	/mcp	Streamable HTTP endpoint path
MCP_TOKEN	(empty = no auth)	Bearer token for authentication

License

MIT