Unraid MCP Server

🚀 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

📋 Table of Contents

• Quick Start
• Installation
• Configuration
• Available Tools & Resources
• Development
• Architecture
• Troubleshooting

🚀 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

2. Configure Environment

3. Deploy with Docker (Recommended)

OR 3. Run for Development

📦 Installation

🐳 Docker Deployment (Recommended)

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

Manual Docker Build

🔧 Development Installation

For development and testing:

⚙️ Configuration

Environment Variables

Create .env file in the project root:

Transport Options

🛠️ 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

Code Quality Commands

Development Workflow

🏗️ 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

🐛 Troubleshooting

Common Issues

🔥 Port Already in Use

🔧 Connection Refused

📝 Import Errors

🔍 Debug Mode

Health Check

📄 License

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

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Run tests: uv run pytest
4. Commit changes: git commit -m 'Add amazing feature'
5. Push to branch: git push origin feature/amazing-feature
6. 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