npx mcpbar@latest edit -c claude

Unraid MCP Server

This server provides an MCP interface to interact with an Unraid server's GraphQL API.

Setup

This section describes the setup for local development without Docker. For Docker-based deployment, see the "Docker" section below.

1. Ensure your main project dependencies (including fastmcp, python-dotenv, httpx) are installed. If your project uses pyproject.toml, this is typically done via a command like uv pip install -e . or pip install -e . from the project root.
2. Navigate to the directory containing unraid-mcp-server.py (e.g., src/unraid-mcp/ or the project root if it's there).
3. Copy .env.example to .env: cp .env.example .env
4. Edit .env and fill in your Unraid and MCP server details:
   • UNRAID_API_URL: Your Unraid GraphQL endpoint (e.g., http://your-unraid-ip/graphql). Required.
   • UNRAID_API_KEY: Your Unraid API key. Required.
   • UNRAID_MCP_TRANSPORT (optional, defaults to sse for local non-Docker. streamable-http is recommended for new setups). Valid options: streamable-http, sse, stdio.
   • UNRAID_MCP_HOST (optional, defaults to 0.0.0.0 for network transports, listens on all interfaces).
   • UNRAID_MCP_PORT (optional, defaults to 6970 for network transports).
   • UNRAID_MCP_LOG_LEVEL (optional, defaults to INFO). Examples: DEBUG, INFO, WARNING, ERROR.
   • UNRAID_MCP_LOG_FILE (optional, defaults to unraid-mcp.log in the script's directory).
   • UNRAID_VERIFY_SSL (optional, defaults to true. Set to false for self-signed certificates, or provide a path to a CA bundle).

Running the Server

From the project root (yarr-mcp/):

python src/unraid-mcp/unraid-mcp-server.py

Or from src/unraid-mcp/:

python unraid-mcp-server.py

The server will start, by default using SSE transport on port 6970.

Implemented Tools

Below is a list of the implemented tools and their basic functions. Refer to the Unraid GraphQL schema for detailed response structures.

• get_system_info(): Retrieves comprehensive system, OS, CPU, memory, and hardware information.
• get_array_status(): Gets the current status of the storage array, capacity, and disk details.
• list_docker_containers(skip_cache: Optional[bool] = False): Lists all Docker containers.
• manage_docker_container(container_id: str, action: str): Starts or stops a Docker container (action: "start" or "stop").
• get_docker_container_details(container_identifier: str): Gets detailed info for a specific Docker container by ID or name.
• list_vms(): Lists all Virtual Machines and their states.
• manage_vm(vm_id: str, action: str): Manages a VM (actions: "start", "stop", "pause", "resume", "forceStop", "reboot").
• get_vm_details(vm_identifier: str): Gets details for a specific VM by ID or name.
• get_shares_info(): Retrieves information about all user shares.
• get_notifications_overview(): Gets an overview of system notifications (counts by severity/status).
• list_notifications(type: str, offset: int, limit: int, importance: Optional[str] = None): Lists notifications with filters.
• list_available_log_files(): Lists all available log files.
• get_logs(log_file_path: str, tail_lines: Optional[int] = 100): Retrieves content from a specific log file (tails last N lines).
• list_physical_disks(): Lists all physical disks recognized by the system.
• get_disk_details(disk_id: str): Retrieves detailed SMART info and partition data for a specific physical disk.
• get_unraid_variables(): Retrieves a wide range of Unraid system variables and settings.
• get_network_config(): Retrieves network configuration details, including access URLs.
• get_registration_info(): Retrieves Unraid registration details.
• get_connect_settings(): Retrieves settings related to Unraid Connect.

Claude Desktop Client Configuration

If your Unraid MCP Server is running on localhost:6970 (the default for SSE):

Create or update your Claude Desktop MCP settings file at ~/.config/claude/claude_mcp_settings.jsonc (create the claude directory if it doesn't exist). Add or update the entry for this server:

{
  "mcp_servers": {
    "unraid": { // Use a short, descriptive name for the client
      "url": "http://localhost:6970/mcp", // Default path for FastMCP SSE is /mcp
      "disabled": false,
      "timeout": 60, // Optional: timeout in seconds for requests
      "transport": "sse" // Explicitly set transport if not default or for clarity
    }
    // ... other server configurations
  }
}

Make sure the url matches your UNRAID_MCP_HOST and UNRAID_MCP_PORT settings if you've changed them from the defaults.

(Details to be added after implementation based on the approved toolset.)

Docker

This application can be containerized using Docker.

Prerequisites

• Docker installed and running.

Building the Image

1. Navigate to the root directory of this project (unraid-mcp).

2. Build the Docker image:

   docker build -t unraid-mcp-server .
   

Running the Container

To run the container, you'll need to provide the necessary environment variables. You can do this directly on the command line or by using an environment file.

Option 1: Using an environment file (recommended)

1. Create a file named .env.local in the project root (this file is in .dockerignore and won't be copied into the image).

2. Add your environment variables to .env.local:

   UNRAID_API_URL=http://your-unraid-ip/graphql
   UNRAID_API_KEY=your-unraid-api-key
   # Optional: override default port
   # UNRAID_MCP_PORT=6971 
   # Optional: override log level
   # UNRAID_MCP_LOG_LEVEL=DEBUG
   # Optional: SSL verification settings
   # UNRAID_VERIFY_SSL=false
   

3. Run the container, mounting the .env.local file:

   docker run -d --name unraid-mcp --restart unless-stopped -p 6970:6970 --env-file .env.local unraid-mcp-server
   

   • -d: Run in detached mode.
   • --name unraid-mcp: Assign a name to the container.
   • --restart unless-stopped: Restart policy.
   • -p 6970:6970: Map port 6970 on the host to port 6970 in the container. Adjust if you changed UNRAID_MCP_PORT.
   • --env-file .env.local: Load environment variables from the specified file.

Option 2: Providing environment variables directly

docker run -d --name unraid-mcp --restart unless-stopped -p 6970:6970 \
  -e UNRAID_API_URL="http://your-unraid-ip/graphql" \
  -e UNRAID_API_KEY="your-unraid-api-key" \
  unraid-mcp-server

Accessing Logs

To view the logs of the running container:

docker logs unraid-mcp

Follow logs in real-time:

docker logs -f unraid-mcp

Stopping and Removing the Container

(Using docker run commands)

docker stop unraid-mcp
docker rm unraid-mcp

Using Docker Compose

A docker-compose.yml file is provided for easier management.

Prerequisites:

• Docker Compose installed (usually included with Docker Desktop).
• Ensure you have an .env.local file in the same directory as docker-compose.yml with your UNRAID_API_URL and UNRAID_API_KEY (and any other overrides). See "Option 1: Using an environment file" in the docker run section above for an example .env.local content.
• If you haven't built the image yet, Docker Compose can build it for you if you uncomment the build section in docker-compose.yml or build it manually first: docker build -t unraid-mcp-server .

Starting the service:

docker-compose up -d

This will start the unraid-mcp service in detached mode.

Viewing logs:

docker-compose logs -f unraid-mcp

Stopping the service:

docker-compose down

This stops and removes the container defined in the docker-compose.yml file.

Claude Desktop Client Configuration (for Docker)

docker stop unraid-mcp
docker rm unraid-mcp

Claude Desktop Client Configuration (for Docker)

If your Unraid MCP Server is running in Docker and exposed on localhost:6970 (default Docker setup):

Create or update your Claude Desktop MCP settings file at ~/.config/claude/claude_mcp_settings.jsonc. Add or update the entry for this server:

{
  "mcp_servers": {
    "unraid": { // Use a short, descriptive name for the client
      "url": "http://localhost:6970/mcp", // Default path for FastMCP streamable-http is /mcp
      "disabled": false,
      "timeout": 60, // Optional: timeout in seconds for requests
      "transport": "streamable-http" // Ensure this matches the server's transport
    }
    // ... other server configurations
  }
}

Make sure the url (host and port) matches your Docker port mapping. The default transport in the Dockerfile is streamable-http. # unraid-mcp