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