unraid-mcp
installs/mo · pypistarsforks
How to install unraid-mcp?
dinglebear-ai/unraid-mcp
$git clone https://github.com/dinglebear-ai/unraid-mcpQuery, monitor, and manage Unraid servers via GraphQL API through MCP tools. Supports system info, Docker, VMs, array/parity, notifications, plugins, rclone, and live telemetry.
README.md
| 1 | # Unraid MCP |
| 2 | |
| 3 | <!-- mcp-name: tv.tootie/unraid-mcp --> |
| 4 | |
| 5 | [](https://pypi.org/project/unraid-mcp/) [](https://github.com/jmagar/unraid-mcp/pkgs/container/unraid-mcp) |
| 6 | |
| 7 | GraphQL-backed MCP server for Unraid. Exposes a unified `unraid` tool for system inspection, management operations, live telemetry, and destructive actions gated by explicit confirmation. |
| 8 | |
| 9 | ## Installation |
| 10 | |
| 11 | The plugin lives at `plugins/unraid/` and launches the server with |
| 12 | `uvx unraid-mcp` (the published [PyPI package](https://pypi.org/project/unraid-mcp/)), |
| 13 | so no local checkout is required once it's installed. You'll need |
| 14 | [`uv`](https://docs.astral.sh/uv/) on your `PATH`. |
| 15 | |
| 16 | ### Claude Code (plugin + marketplace) |
| 17 | |
| 18 | Add this repo as a marketplace, then install the plugin: |
| 19 | |
| 20 | ```text |
| 21 | /plugin marketplace add jmagar/unraid-mcp |
| 22 | /plugin install unraid-mcp@unraid-mcp |
| 23 | ``` |
| 24 | |
| 25 | `marketplace add` accepts the `owner/repo` shorthand (or a full git URL / local |
| 26 | path). After install, Claude Code prompts for **Unraid GraphQL API URL** and |
| 27 | **Unraid API Key** (the plugin's `userConfig`); they're passed to the server and |
| 28 | persisted to `~/.unraid-mcp/.env` by the SessionStart hook. |
| 29 | |
| 30 | ### Codex (plugin + marketplace) |
| 31 | |
| 32 | The repo ships a Codex marketplace manifest at `.agents/plugins/marketplace.json`: |
| 33 | |
| 34 | ```bash |
| 35 | codex plugin marketplace add jmagar/unraid-mcp |
| 36 | # then enable `unraid-mcp@unraid-mcp` from the Codex `/plugins` view |
| 37 | ``` |
| 38 | |
| 39 | Codex does not expand plugin-config placeholders into the MCP env, so export your |
| 40 | credentials in the shell that launches Codex (the manifest forwards them by name): |
| 41 | |
| 42 | ```bash |
| 43 | export UNRAID_API_URL="https://tower.local/graphql" |
| 44 | export UNRAID_API_KEY="your-api-key" |
| 45 | ``` |
| 46 | |
| 47 | Alternatively, populate `~/.unraid-mcp/.env` (run `uvx unraid-mcp setup`) — the |
| 48 | server reads it automatically. |
| 49 | |
| 50 | ### Gemini CLI (extension) |
| 51 | |
| 52 | Install the extension straight from the repo (`gemini extensions install` reads |
| 53 | `gemini-extension.json` from the repo root): |
| 54 | |
| 55 | ```bash |
| 56 | gemini extensions install https://github.com/jmagar/unraid-mcp |
| 57 | ``` |
| 58 | |
| 59 | Gemini prompts for the `UNRAID_API_URL` and `UNRAID_API_KEY` settings on install |
| 60 | and exports them to the server's environment. |
| 61 | |
| 62 | ### Run the server directly with uvx |
| 63 | |
| 64 | No clone needed — run the published package on demand: |
| 65 | |
| 66 | ```bash |
| 67 | export UNRAID_API_URL="https://tower.local/graphql" |
| 68 | export UNRAID_API_KEY="your-api-key" |
| 69 | uvx unraid-mcp |
| 70 | ``` |
| 71 | |
| 72 | ### Local development |
| 73 | |
| 74 | ```bash |
| 75 | uv sync --dev |
| 76 | uv run unraid-mcp-server |
| 77 | ``` |
| 78 | |
| 79 | Equivalent entrypoints: |
| 80 | |
| 81 | ```bash |
| 82 | uv run unraid-mcp |
| 83 | uv run python -m unraid_mcp |
| 84 | ``` |
| 85 | |
| 86 | ### Docker |
| 87 | |
| 88 | ```bash |
| 89 | docker compose up -d |
| 90 | ``` |
| 91 | |
| 92 | ### Claude Desktop |
| 93 | |
| 94 | Newer Claude Desktop builds may reject the raw `streamable-http` URL config when the |
| 95 | server runs in Docker. Connect through the `mcp-remote` proxy instead — see |
| 96 | [docs/mcp/CONNECT.md](docs/mcp/CONNECT.md#claude-desktop-via-mcp-remote-proxy) for the |
| 97 | macOS/Linux and Windows config snippets. |
| 98 | |
| 99 | ## Configuration |
| 100 | |
| 101 | Create `.env` from `.env.example`: |
| 102 | |
| 103 | ```bash |
| 104 | just setup |
| 105 | ``` |
| 106 | |
| 107 | ### Environment variables |
| 108 | |
| 109 | | Variable | Required | Default | Description | |
| 110 | | --- | --- | --- | --- | |
| 111 | | `UNRAID_API_URL` | Yes | — | GraphQL endpoint URL, e.g. `https://tower.local/graphql` | |
| 112 | | `UNRAID_API_KEY` | Yes | — | Unraid API key (see below) | |
| 113 | | `UNRAID_MCP_TRANSPORT` | No | `streamable-http` | Transport: `streamable-http`, `stdio`, or legacy `sse` (deprecated; removed in v3.0.0) | |
| 114 | | `UNRAID_MCP_HOST` | No | `127.0.0.1` bare metal; Docker sets `0.0.0.0` | Bind address for HTTP transports | |
| 115 | | `UNRAID_MCP_PORT` | No | `6970` | Listen port for HTTP transports | |
| 116 | | `UNRAID_MCP_MAX_RESPONSE_BYTES` | No | `40000` | Max serialized tool-response size; over-cap responses return a parseable truncation marker | |
| 117 | | `UNRAID_MCP_BEARER_TOKEN` | Conditional | — | Static Bearer token for HTTP transports; auto-generated on first start if unset | |
| 118 | | `UNRAID_MCP_DISABLE_HTTP_AUTH` | No | `false` | Set `true` to skip Bearer auth (use behind a reverse proxy that handles auth) | |
| 119 | | `UNRAID_MCP_TRUST_PROXY` | Conditional | `false` | Required when disabling HTTP auth while binding a non-loopback interface | |
| 120 | | `UNRAID_MCP_GOOGLE_CLIENT_ID` | No | — | Google OAuth client ID; setting both client ID and secret enables OAuth for HTTP transports (required for claude.ai connectors). An explicitly set `UNRAID_MCP_BEARER_TOKEN` stays valid alongside OAuth | |
| 121 | | `UNRAID_MCP_GOOGLE_CLIENT_SECRET` | No | — | Google OAuth client secret | |
| 122 | | `UNRAID_MCP_GOOGLE_BASE_URL` | Conditional | — | Public server base URL, required when Google OAuth is enabled | |
| 123 | | `UNRAID_MCP_GOOGLE_REQUIRED_SCOPES` | No | `openid` + `userinfo.email` | Comma/space-separated OAuth scopes | |
| 124 | | `UNRAID_MCP_GOOGLE_ALLOWED_EMAILS` | Conditional | — | Verified Google emails allowed to use the MCP server | |
| 125 | | `UNRAID_MCP_GOOGLE_ALLOWED_DOMAINS` | Conditional | — | Verified Google email domains allowed to use the MCP server | |
| 126 | | `UNRAID_MCP_GOOGLE_ALLOW_ANY_USER` | No | `false` | Expli |
People who liked this also viewed
6 picksType
- mcp-proxy-for-awsAWS MCP Proxy ServerMCP ServersJul 2026
- pydantic-ai-backendFile Storage & Sandbox Backends for Pydantic AI: console tools for file operations, Docker-isolated sandboxes for safe execution, and permission system with presets for access control. Enables secure multi-user handling and testing in agents via in-memory, local, or containerized storage.MCP ServersJul 2026
- mcp-for-argocdAn implementation of Model Context Protocol (MCP) server for Argo CD.MCP ServersJul 2026
- heroku-mcp-serverHeroku Platform MCP Server using the Heroku CLIMCP ServersJul 2026
- ghost-mcpA Model Context Protocol (MCP) server for interacting with Ghost CMS through LLM interfaces like Claude. Allow you to control your Ghost blog by simply asking Claude etc.MCP ServersApr 2026
- Google DriveUpload, organize, and share files in the cloud. Manage folders, set permissions, and search across stored documents.MCP Serversrecently
