forked from HomeLab/unraid-mcp
2697c269a3
**Project Configuration:** - Enhance pyproject.toml with comprehensive metadata, keywords, and classifiers - Add LICENSE file (MIT) for proper open-source distribution - Add PUBLISHING.md with comprehensive publishing guidelines - Update .gitignore to exclude tool artifacts (.cache, .pytest_cache, .ruff_cache, .ty_cache) - Ignore documentation working directories (.docs, .full-review, docs/plans, docs/sessions) **Documentation:** - Add extensive Unraid API research documentation - API source code analysis and resolver mapping - Competitive analysis and feature gap assessment - Release notes analysis (7.0.0, 7.1.0, 7.2.0) - Connect platform overview and remote access documentation - Document known API patterns, limitations, and edge cases **Testing & Code Quality:** - Expand test coverage across all tool modules - Add destructive action confirmation tests - Improve test assertions and error case validation - Refine type annotations for better static analysis **Tool Improvements:** - Enhance error handling consistency across all tools - Improve type safety with explicit type annotations - Refine GraphQL query construction patterns - Better handling of optional parameters and edge cases This commit prepares the project for v0.2.0 release with improved metadata, comprehensive documentation, and enhanced code quality. Co-authored-by: Claude <noreply@anthropic.com>
359 lines
10 KiB
Markdown
359 lines
10 KiB
Markdown
# 🚀 Unraid MCP Server
|
|
|
|
[](https://www.python.org/downloads/)
|
|
[](https://github.com/jlowin/fastmcp)
|
|
[](LICENSE)
|
|
|
|
**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](#-quick-start)
|
|
- [Installation](#-installation)
|
|
- [Configuration](#-configuration)
|
|
- [Available Tools & Resources](#-available-tools--resources)
|
|
- [Development](#-development)
|
|
- [Architecture](#-architecture)
|
|
- [Troubleshooting](#-troubleshooting)
|
|
|
|
---
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### Prerequisites
|
|
- Docker and Docker Compose (recommended)
|
|
- OR Python 3.10+ with [uv](https://github.com/astral-sh/uv) for development
|
|
- Unraid server with GraphQL API enabled
|
|
|
|
### 1. Clone Repository
|
|
```bash
|
|
git clone https://github.com/jmagar/unraid-mcp
|
|
cd unraid-mcp
|
|
```
|
|
|
|
### 2. Configure Environment
|
|
```bash
|
|
cp .env.example .env
|
|
# Edit .env with your Unraid API details
|
|
```
|
|
|
|
### 3. Deploy with Docker (Recommended)
|
|
```bash
|
|
# Start with Docker Compose
|
|
docker compose up -d
|
|
|
|
# View logs
|
|
docker compose logs -f unraid-mcp
|
|
```
|
|
|
|
### OR 3. Run for Development
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# Format code
|
|
uv run black unraid_mcp/
|
|
|
|
# Lint code
|
|
uv run ruff check unraid_mcp/
|
|
|
|
# Type checking
|
|
uv run ty check unraid_mcp/
|
|
|
|
# Run tests
|
|
uv run pytest
|
|
```
|
|
|
|
### Development Workflow
|
|
```bash
|
|
# 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**
|
|
```bash
|
|
./dev.sh # Automatically kills existing processes
|
|
```
|
|
|
|
**🔧 Connection Refused**
|
|
```bash
|
|
# Check Unraid API configuration
|
|
curl -k "${UNRAID_API_URL}" -H "X-API-Key: ${UNRAID_API_KEY}"
|
|
```
|
|
|
|
**📝 Import Errors**
|
|
```bash
|
|
# Reinstall dependencies
|
|
uv sync --reinstall
|
|
```
|
|
|
|
**🔍 Debug Mode**
|
|
```bash
|
|
# Enable debug logging
|
|
export UNRAID_MCP_LOG_LEVEL=DEBUG
|
|
uv run unraid-mcp-server
|
|
```
|
|
|
|
### Health Check
|
|
```bash
|
|
# 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](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](https://github.com/jmagar/unraid-mcp/issues)
|
|
- 💬 Discussions: Use GitHub Discussions for questions
|
|
|
|
---
|
|
|
|
*Built with ❤️ for the Unraid community* |