truenas

This MCP server enables natural-language control of TrueNAS Scale Custom Apps by converting Docker Compose configurations into TrueNAS Custom App deployments and providing tooling to manage, monitor, and validate those apps. It exposes a suite of 11 MCP tools for tasks such as listing apps, deploying new apps, updating configurations, starting/stopping apps, and retrieving logs. The server integrates with Claude (or other MCP clients) via a WebSocket-enabled API, allowing you to issue commands in plain language (e.g., deploy a Compose file, show app status, fetch logs) and have them translated into TrueNAS API calls or Docker Compose conversions. In development mode, a mock TrueNAS path allows you to test commands without requiring a real TrueNAS system. You’ll configure the server with your TrueNAS host, API key, and connection details, then run it and issue natural-language commands through your MCP client.

To use the Claude integration shown in the documentation, you can point Claude to run the server script directly or via Poetry, supplying the necessary environment variables. Once connected, you can perform common workflows: list all Custom Apps and their status, deploy a new app from a Docker Compose file as a Custom App, start/stop existing apps, view detailed app status, and fetch logs. You can also convert a Docker Compose file into the corresponding TrueNAS Custom App manifest, including volumes, ports, environment variables, and network settings, with built-in security validations to prevent privileged containers or risky mounts.

Prerequisites

• Python 3.10+ installed on your system
• Poetry for dependency management
• TrueNAS Scale 24.10+ (Electric Eel) with API access

1. Clone the repository

git clone https://github.com/yourusername/truenas-mcp-server.git
cd truenas-mcp-server

2. Install dependencies with Poetry

poetry install

3. Optional: set up pre-commit hooks

poetry run pre-commit install

4. Configure environment variables (see example below) and start the server

# Example environment (adjust values to your environment)
export TRUENAS_HOST="nas.yourdomain.local"
export TRUENAS_API_KEY="your-api-key-here"
export TRUENAS_PORT="443"
export TRUENAS_PROTOCOL="wss"
export TRUENAS_SSL_VERIFY="false"
export DEBUG_MODE="false"
export MOCK_TRUENAS="false"  # set to true to enable mock development

poetry run python src/truenas_mcp/mcp_server.py

5. Claude integration (optional, direct path shown in documentation):

{
  "mcpServers": {
    "truenas-scale": {
      "type": "stdio",
      "command": "python",
      "args": ["/path/to/truenas-mcp-server/src/truenas_mcp/mcp_server.py"],
      "env": {
        "TRUENAS_HOST": "nas.yourdomain.local",
        "TRUENAS_API_KEY": "your-api-key-here",
        "TRUENAS_PORT": "443",
        "TRUENAS_PROTOCOL": "wss",
        "TRUENAS_SSL_VERIFY": "false"
      }
    }
  }
}

If you prefer Poetry execution, you can wrap the command similarly with cwd set to the repository root and use: ["poetry", "run", "python", "src/truenas_mcp/mcp_server.py"] with the same environment variables.

Tips and notes:

• Ensure TRUENAS_SSL_VERIFY is set to false only in development or when using self-signed certs; in production, set it to true.
• The MOCK_TRUENAS flag enables a mock development workflow; set it to true to test commands without a real TrueNAS system.
• The server includes a Docker Compose converter that translates typical Docker Compose configurations into TrueNAS Custom App manifests, including volumes, ports, environment variables, and network settings.
• If you encounter connection issues, verify TRUENAS_HOST, TRUENAS_PORT, and TRUENAS_API_KEY, and ensure the API endpoint is reachable from the server host.
• The project emphasizes security validations to prevent privileged containers and disallowed mounts; review validation outputs when deploying new apps.