🚀 Unraid MCP Server

A powerful MCP (Model Context Protocol) server that provides comprehensive tools to interact with an Unraid server's GraphQL API.

✨ Features

🔧 26 Tools: Complete Unraid management through MCP protocol
🏗️ Modular Architecture: Clean, maintainable, and extensible codebase
⚡ High Performance: Async/concurrent operations with optimized timeouts
🔄 Real-time Data: WebSocket subscriptions for live log streaming
📊 Health Monitoring: Comprehensive system diagnostics and status
🐳 Docker Ready: Full containerization support with Docker Compose
🔒 Secure: Proper SSL/TLS configuration and API key management
📝 Rich Logging: Structured logging with rotation and multiple levels

🚀 Quick Start

Prerequisites

Docker and Docker Compose (recommended)
OR Python 3.10+ with uv for development
Unraid server with GraphQL API enabled

1. Clone Repository

git clone https://github.com/jmagar/unraid-mcp
cd unraid-mcp

2. Configure Environment

cp .env.example .env
# Edit .env with your Unraid API details

3. Deploy with Docker (Recommended)

# Start with Docker Compose
docker compose up -d

# View logs
docker compose logs -f unraid-mcp

OR 3. Run for Development

# Install dependencies
uv sync

# Run development server
./dev.sh

📦 Installation

🐳 Docker Deployment (Recommended)

The easiest way to run the Unraid MCP Server is with Docker:

# Clone repository
git clone https://github.com/jmagar/unraid-mcp
cd unraid-mcp

# Set required environment variables
export UNRAID_API_URL="http://your-unraid-server/graphql"
export UNRAID_API_KEY="your_api_key_here"

# Deploy with Docker Compose
docker compose up -d

# View logs
docker compose logs -f unraid-mcp

Manual Docker Build

# Build and run manually
docker build -t unraid-mcp-server .
docker run -d --name unraid-mcp \
  --restart unless-stopped \
  -p 6970:6970 \
  -e UNRAID_API_URL="http://your-unraid-server/graphql" \
  -e UNRAID_API_KEY="your_api_key_here" \
  unraid-mcp-server

🔧 Development Installation

For development and testing:

# Clone repository
git clone https://github.com/jmagar/unraid-mcp
cd unraid-mcp

# Install dependencies with uv
uv sync

# Install development dependencies  
uv sync --group dev

# Configure environment
cp .env.example .env
# Edit .env with your settings

# Run development server
./dev.sh

⚙️ Configuration

Environment Variables

Create .env file in the project root:

# Core API Configuration (Required)
UNRAID_API_URL=https://your-unraid-server-url/graphql
UNRAID_API_KEY=your_unraid_api_key

# MCP Server Settings
UNRAID_MCP_TRANSPORT=streamable-http  # streamable-http (recommended), sse (deprecated), stdio
UNRAID_MCP_HOST=0.0.0.0
UNRAID_MCP_PORT=6970

# Logging Configuration
UNRAID_MCP_LOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR
UNRAID_MCP_LOG_FILE=unraid-mcp.log

# SSL/TLS Configuration  
UNRAID_VERIFY_SSL=true  # true, false, or path to CA bundle

# Optional: Log Stream Configuration
# UNRAID_AUTOSTART_LOG_PATH=/var/log/syslog  # Path for log streaming resource

Transport Options

Transport	Description	Use Case
`streamable-http`	HTTP-based (recommended)	Most compatible, best performance
`sse`	Server-Sent Events (deprecated)	Legacy support only
`stdio`	Standard I/O	Direct integration scenarios

🛠️ Available Tools & Resources

System Information & Status

get_system_info() - Comprehensive system, OS, CPU, memory, hardware info
get_array_status() - Storage array status, capacity, and disk details
get_unraid_variables() - System variables and settings
get_network_config() - Network configuration and access URLs
get_registration_info() - Unraid registration details
get_connect_settings() - Unraid Connect configuration

Docker Container Management

list_docker_containers() - List all containers with caching options
manage_docker_container(id, action) - Start/stop containers (idempotent)
get_docker_container_details(identifier) - Detailed container information

Virtual Machine Management

list_vms() - List all VMs and their states
manage_vm(id, action) - VM lifecycle (start/stop/pause/resume/reboot)
get_vm_details(identifier) - Detailed VM information

Storage & File Systems

get_shares_info() - User shares information
list_physical_disks() - Physical disk discovery
get_disk_details(disk_id) - SMART data and detailed disk info

Monitoring & Diagnostics

health_check() - Comprehensive system health assessment
get_notifications_overview() - Notification counts by severity
list_notifications(type, offset, limit) - Filtered notification listing
list_available_log_files() - Available system logs
get_logs(path, tail_lines) - Log file content retrieval

Cloud Storage (RClone)

list_rclone_remotes() - List configured remotes
get_rclone_config_form(provider) - Configuration schemas
create_rclone_remote(name, type, config) - Create new remote
delete_rclone_remote(name) - Remove existing remote

Real-time Subscriptions & Resources

test_subscription_query(query) - Test GraphQL subscriptions
diagnose_subscriptions() - Subscription system diagnostics

MCP Resources (Real-time Data)

unraid://logs/stream - Live log streaming from /var/log/syslog with WebSocket subscriptions

Note: MCP Resources provide real-time data streams that can be accessed via MCP clients. The log stream resource automatically connects to your Unraid system logs and provides live updates.

🔧 Development

Project Structure

unraid-mcp/
├── unraid_mcp/               # Main package
│   ├── main.py               # Entry point
│   ├── config/               # Configuration management
│   │   ├── settings.py       # Environment & settings
│   │   └── logging.py        # Logging setup
│   ├── core/                 # Core infrastructure  
│   │   ├── client.py         # GraphQL client
│   │   ├── exceptions.py     # Custom exceptions
│   │   └── types.py          # Shared data types
│   ├── subscriptions/        # Real-time subscriptions
│   │   ├── manager.py        # WebSocket management
│   │   ├── resources.py      # MCP resources
│   │   └── diagnostics.py    # Diagnostic tools
│   ├── tools/                # MCP tool categories
│   │   ├── docker.py         # Container management
│   │   ├── system.py         # System information
│   │   ├── storage.py        # Storage & monitoring
│   │   ├── health.py         # Health checks
│   │   ├── virtualization.py # VM management
│   │   └── rclone.py         # Cloud storage
│   └── server.py             # FastMCP server setup
├── logs/                     # Log files (auto-created)
├── dev.sh                    # Development script  
└── docker-compose.yml        # Docker Compose deployment

Code Quality Commands

# Format code
uv run black unraid_mcp/

# Lint code  
uv run ruff check unraid_mcp/

# Type checking
uv run mypy unraid_mcp/

# Run tests
uv run pytest

Development Workflow

# Start development server (kills existing processes safely)
./dev.sh

# Stop server only
./dev.sh --kill

🏗️ Architecture

Core Principles

Modular Design: Separate concerns across focused modules
Async First: All operations are non-blocking and concurrent-safe
Error Resilience: Comprehensive error handling with graceful degradation
Configuration Driven: Environment-based configuration with validation
Observability: Structured logging and health monitoring

Key Components

Component	Purpose
FastMCP Server	MCP protocol implementation and tool registration
GraphQL Client	Async HTTP client with timeout management
Subscription Manager	WebSocket connections for real-time data
Tool Modules	Domain-specific business logic (Docker, VMs, etc.)
Configuration System	Environment loading and validation
Logging Framework	Structured logging with file rotation

🐛 Troubleshooting

Common Issues

🔥 Port Already in Use

./dev.sh  # Automatically kills existing processes

🔧 Connection Refused

# Check Unraid API configuration
curl -k "${UNRAID_API_URL}" -H "X-API-Key: ${UNRAID_API_KEY}"

📝 Import Errors

# Reinstall dependencies
uv sync --reinstall

🔍 Debug Mode

# Enable debug logging
export UNRAID_MCP_LOG_LEVEL=DEBUG
uv run unraid-mcp-server

Health Check

# Use the built-in health check tool via MCP client
# or check logs at: logs/unraid-mcp.log

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Run tests: uv run pytest
Commit changes: git commit -m 'Add amazing feature'
Push to branch: git push origin feature/amazing-feature
Open a Pull Request

📞 Support

📚 Documentation: Check inline code documentation
🐛 Issues: GitHub Issues
💬 Discussions: Use GitHub Discussions for questions

Built with ❤️ for the Unraid community