Unraid MCP server for AI agents

The Unraid MCP Server provides comprehensive tools for interacting with an Unraid server's GraphQL API through the Model Context Protocol. It offers 26 tools for complete Unraid management, real-time data streaming, and system monitoring in a high-performance, Docker-ready package.

Installation

Docker Deployment (Recommended)

# 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

Configuration

Environment Variables

Create a .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

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

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "unraid" '{"url":"http://localhost:6970/mcp","disabled":false,"timeout":60,"transport":"sse"}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "unraid": {
            "url": "http://localhost:6970/mcp",
            "disabled": false,
            "timeout": 60,
            "transport": "sse"
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "unraid": {
            "url": "http://localhost:6970/mcp",
            "disabled": false,
            "timeout": 60,
            "transport": "sse"
        }
    }
}

3. Restart Claude Desktop for the changes to take effect