svnstfns/truenas-mcp-server
If you are the rightful owner of truenas-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
A Model Context Protocol (MCP) server for managing TrueNAS Scale Custom Apps through Docker-based deployments.
TrueNAS Scale MCP Server
A Model Context Protocol (MCP) server for managing TrueNAS Scale Custom Apps through Docker-based deployments.
Overview
This MCP server enables AI assistants like Claude to manage TrueNAS Scale Custom Apps using natural language commands. It provides tools for deploying, managing, and monitoring Docker Compose applications on TrueNAS Scale systems.
Features
- 11 MCP Tools for comprehensive Custom App management
- Docker Compose Conversion to TrueNAS Custom App format
- Security Validation with input sanitization
- Mock Development Mode for testing without TrueNAS access
- Comprehensive Test Suite with >80% coverage
- WebSocket API Integration with TrueNAS Electric Eel
Quick Start
Prerequisites
- Python 3.10+
- Poetry for dependency management
- TrueNAS Scale 24.10+ (Electric Eel) with API access
Installation
# Clone the repository
git clone https://github.com/yourusername/truenas-mcp-server.git
cd truenas-mcp-server
# Install dependencies
poetry install
# Install pre-commit hooks (optional)
poetry run pre-commit install
Configuration
Set up environment variables for your TrueNAS system:
export TRUENAS_HOST="nas.pvnkn3t.lan"
export TRUENAS_API_KEY="your-api-key-here"
export TRUENAS_PORT="443"
export TRUENAS_PROTOCOL="wss"
export TRUENAS_SSL_VERIFY="false" # Use "true" for production
export DEBUG_MODE="false"
Testing the Server
# Test with mock TrueNAS (no real TrueNAS required)
MOCK_TRUENAS=true poetry run python src/truenas_mcp/mcp_server.py
# Test with real TrueNAS
poetry run python src/truenas_mcp/mcp_server.py
Claude Code Integration
Add this server to your Claude Code MCP configuration:
Option 1: Direct Python Execution
Add to your ~/.claude/mcp-servers/production.json
:
{
"mcpServers": {
"truenas-scale": {
"type": "stdio",
"command": "python",
"args": ["/path/to/truenas-mcp-server/src/truenas_mcp/mcp_server.py"],
"env": {
"TRUENAS_HOST": "nas.pvnkn3t.lan",
"TRUENAS_API_KEY": "your-api-key-here",
"TRUENAS_PORT": "443",
"TRUENAS_PROTOCOL": "wss",
"TRUENAS_SSL_VERIFY": "false"
}
}
}
}
Option 2: Poetry Execution
{
"mcpServers": {
"truenas-scale": {
"type": "stdio",
"command": "poetry",
"args": ["run", "python", "src/truenas_mcp/mcp_server.py"],
"cwd": "/path/to/truenas-mcp-server",
"env": {
"TRUENAS_HOST": "nas.pvnkn3t.lan",
"TRUENAS_API_KEY": "your-api-key-here",
"TRUENAS_PORT": "443",
"TRUENAS_PROTOCOL": "wss",
"TRUENAS_SSL_VERIFY": "false"
}
}
}
}
Usage Examples
Once configured, you can use these natural language commands with Claude:
# List all Custom Apps
claude "List all my TrueNAS Custom Apps and their status"
# Deploy a new app
claude "Deploy this docker-compose.yml as a Custom App named 'my-app'"
# Manage existing apps
claude "Stop the Custom App named 'plex'"
claude "Start the Custom App named 'nextcloud'"
claude "Show detailed status of Custom App 'jellyfin'"
# Get logs
claude "Show me the last 50 lines of logs from Custom App 'nginx'"
# Delete an app
claude "Delete the Custom App 'old-app' including its volumes"
Available MCP Tools
Connection Management
test_connection
- Test TrueNAS API connectivity
Custom App Management
list_custom_apps
- List all Custom Apps with statusget_custom_app_status
- Get detailed app informationstart_custom_app
- Start a stopped appstop_custom_app
- Stop a running app
Deployment Tools
deploy_custom_app
- Deploy new app from Docker Composeupdate_custom_app
- Update existing app configurationdelete_custom_app
- Remove app and optionally its volumes
Validation & Monitoring
validate_compose
- Validate Docker Compose for TrueNAS compatibilityget_app_logs
- Retrieve application logs
Development
Running Tests
# Run all tests
poetry run pytest
# Run with coverage
poetry run pytest --cov=src/truenas_mcp --cov-report=html
# Run specific test categories
poetry run pytest -m unit # Unit tests only
poetry run pytest -m integration # Integration tests only
Code Quality
# Format code
poetry run black .
# Lint code
poetry run ruff check . --fix
# Type checking
poetry run mypy .
# Run all quality checks
poetry run pre-commit run --all-files
Mock Development
For development without a TrueNAS system:
# Enable mock mode
export MOCK_TRUENAS=true
# Run the server
poetry run python src/truenas_mcp/mcp_server.py
Docker Compose Conversion
The server automatically converts Docker Compose files to TrueNAS Custom App format:
Supported Features
- Volume mounts (named volumes ā IX volumes, bind mounts ā host paths)
- Port forwarding (container ports ā host ports)
- Environment variables
- Network configuration (bridge/host modes)
- Restart policies
Security Validations
- Prevents privileged container mode
- Blocks dangerous system directory mounts
- Validates port conflicts
- Enforces resource limits
Troubleshooting
Connection Issues
# Test API connectivity
curl -k -H "Authorization: Bearer YOUR_API_KEY" https://nas.pvnkn3t.lan/api/v2.0/system/info
# Check WebSocket connection
export TRUENAS_HOST=nas.pvnkn3t.lan TRUENAS_API_KEY=your-key
poetry run python -c "
import asyncio
from src.truenas_mcp.truenas_client import TrueNASClient
asyncio.run(TrueNASClient().test_connection())
"
Common Issues
- "Connection refused": Check
TRUENAS_HOST
andTRUENAS_PORT
- "Authentication failed": Verify
TRUENAS_API_KEY
is correct - "SSL verification failed": Set
TRUENAS_SSL_VERIFY=false
for self-signed certificates
Architecture
āāāāāāāāāāāāāāāāāāā MCP Protocol āāāāāāāāāāāāāāāāāāāā WebSocket API āāāāāāāāāāāāāāāāāāā
ā AI Assistant ā āāāāāāāāāāāāāāāāāāāāŗ ā TrueNAS MCP ā āāāāāāāāāāāāāāāāāāāāŗ ā TrueNAS Scale ā
ā (Claude.ai) ā JSON-RPC 2.0 ā Server ā auth + app.* ā Electric Eel ā
āāāāāāāāāāāāāāāāāāā āāāāāāāāāāāāāāāāāāāā āāāāāāāāāāāāāāāāāāā
Core Components
- MCP Protocol Handler: Manages client communication and capability exchange
- TrueNAS API Client: Handles WebSocket connection and authentication
- Docker Compose Converter: Transforms Docker Compose to TrueNAS Custom App format
- Validation Engine: Validates inputs and security constraints
- Tool Registry: Manages available tools and their schemas
Contributing
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature
- Make your changes
- Run tests:
poetry run pytest
- Run quality checks:
poetry run pre-commit run --all-files
- Commit your changes:
git commit -m 'Add amazing feature'
- Push to the branch:
git push origin feature/amazing-feature
- Open a Pull Request
License
This project is licensed under the MIT License - see the file for details.
Requirements
This implementation fulfills the complete specification with:
- ā 11 MCP tools with JSON schema validation
- ā WebSocket API integration with TrueNAS Electric Eel
- ā Docker Compose to Custom App conversion
- ā Comprehensive security validation
- ā >80% test coverage
- ā Production-ready error handling and logging
Support
For issues, questions, or contributions, please open an issue on GitHub.
Status: Production Ready ā
MCP Protocol: 2.0 Compatible
TrueNAS: Electric Eel (24.10+) Compatible