# Reported issues for Unraid MCP Pod holds 19 of 20 problems reported by people outside the maintainer team. Issues filed by the project's own owners, members and collaborators are excluded entirely — a maintainer's release checklist is not a warning to a prospective user. Back to [Unraid MCP](/mcp/unraid-mcp). ## Most discussed ### Feature request: OAuth 2.1 support for claude.ai connector Hey, love the project. Running it on my Unraid 7.3 box and it works great with Claude Code and Claude Desktop via Bearer token. The problem is claude.ai's custom connector UI forces OAuth 2.1 with dynamic client registration — there's no way to provide a static Bearer token. So it's completely unusable from the web UI right now. Home Assistant's MCP server is a good reference — they use HA's existing auth system as the OAuth provider and it works perfectly with claude.ai. Something simila [Read the thread](https://github.com/dinglebear-ai/unraid/issues/191) · 2026-07-20 · closed · external user · 1 comment ### Schema drift detection mechanism digging into mcp servers for my own home-lab stuff, curious how the schema drift detection actually works. scheduled diff against the live graphql schema? the workflow file names don't say. [Read the thread](https://github.com/dinglebear-ai/unraid/issues/176) · 2026-07-16 · closed · external user · 3 comments ### Unraid GraphQL schema drift detected The vendored `docs/unraid/UNRAID-SCHEMA.graphql` no longer matches Unraid's published SDL at `unraid/api@main`. Re-vendor the schema, then run the schema and dispatch contract tests to surface which queries, mutations, and mock responses need updates. The complete `schema.diff`, `schema-summary.md`, and `upstream-schema.graphql` are attached to this workflow run as the `unraid-schema-drift-285017 [Read the thread](https://github.com/dinglebear-ai/unraid/issues/138) · 2026-06-30 · closed · outside contributor · 2 comments ### Codex plugin manifest overrides UNRAID_VERIFY_SSL CA bundle path for self-signed certs ## Summary When using the Codex plugin with an Unraid API endpoint that uses a self-signed certificate, setting `UNRAID_VERIFY_SSL` to a CA-bundle path in `~/.unraid-mcp/.env` is not sufficient. The installed Codex plugin manifest also sets `UNRAID_VERIFY_SSL`, and that manifest-provided environment value is passed directly to the MCP process. Because the manifest currently hard-codes: ```json "UNRAID_VERIFY_SSL": "true" ``` it overrides the `.env` value. The MCP server then falls back to Py [Read the thread](https://github.com/dinglebear-ai/unraid/issues/137) · 2026-06-29 · closed · external user · 1 comment ### Unraid GraphQL schema drift detected The vendored `docs/unraid/UNRAID-SCHEMA.graphql` no longer matches Unraid's published SDL at `unraid/api@main`. Re-vendor the schema, then run the schema and dispatch contract tests to surface which queries, mutations, and mock responses need updates. The complete `schema.diff`, `schema-summary.md`, and `upstream-schema.graphql` are attached to this workflow run as the `unraid-schema-drift-283152 [Read the thread](https://github.com/dinglebear-ai/unraid/issues/107) · 2026-06-24 · closed · outside contributor · 31 comments ### Unraid 7.2 GraphQL Schema Compatibility Issue # Unraid 7.2 GraphQL Schema Compatibility Issue ## Summary On Unraid `7.2` (kernel `6.12.54-Unraid`), multiple MCP tools fail due to GraphQL schema mismatches in `get_system_info` and `health_check` queries. Primary failures observed: - `health_check` returned GraphQL validation errors. - `get_system_info` returned GraphQL validation errors. - Other tools like `get_array_status` and `list_docker_containers` worked. After narrowing/removing schema-volatile fields in those two queries, both t [Read the thread](https://github.com/dinglebear-ai/unraid/issues/9) · 2026-02-14 · closed · external user · 3 comments ### Alternate desktop config json The most recent version of Claude Desktop seems to throw an error with this syntax (running in docker): ``` { "mcp_servers": { "unraid": { "url": "http://:6970/mcp", "disabled": false, "timeout": 60, "transport": "streamable-http" } // ... other server configurations } } ``` Instead I proxied it locally with the mcp-remote package and now it's working (I'm running Claude Desktop in Windows, hence the "wsl" command. ``` "unraid": { " [Read the thread](https://github.com/dinglebear-ai/unraid/issues/2) · 2025-07-03 · closed · external user · 1 comment ### fastmcp>=0.4.0 requires python>=3.10. Error in python import I got errors trying to build the Docker image. Changing this in the Dockerfile fixed it: ``` FROM python:3.12-slim ``` Also when running the image I got errors that ToolError can't be imported from fastmcp. I think it's supposed to be imported from the fastmcp.exceptions library. ``` from fastmcp import FastMCP from fastmcp.exceptions import ToolError ``` [Read the thread](https://github.com/dinglebear-ai/unraid/issues/1) · 2025-07-03 · closed · external user · 1 comment ## Most recent ### Unraid GraphQL schema drift detected (unraid-rs) The vendored `unraid-rs/schema/unraid-schema.graphql` no longer matches Unraid's published SDL (`unraid/api@main`). Re-vendor it (copy the upstream file, re-add the provenance header), then let the cargo schema-contract test surface which queries/fixtures need updating.
diff ```diff --- vendored-body.graphql 2026-08-30 11:35:02.118720548 +0000 +++ ../unraid-py/upstream-schema.graphql 2026-08-30 11:34:54.604709675 +0000 @@ -1192,11 +1192,6 @@ """Add new disk to a [Read the thread](https://github.com/dinglebear-ai/unraid/issues/382) · 2026-08-29 · open · outside contributor · 0 comments ### Unraid GraphQL schema drift detected The vendored `docs/unraid/UNRAID-SCHEMA.graphql` no longer matches Unraid's published SDL at `unraid/api@main`. The compared blob was fetched from immutable commit `97f639fc1dc7484d9f7c4ed0dd2f9e0cd345d38f`. Re-vendor the schema, then run the schema and dispatch contract tests to surface which queries, mutations, and mock responses need updates. The complete `schema.diff`, `schema-summary.md`, an [Read the thread](https://github.com/dinglebear-ai/unraid/issues/381) · 2026-08-29 · open · outside contributor · 0 comments ### Service fails to start on Unraid "exclusive share" setups: FATAL refusing symlinked appdata path /mnt/user/appdata ### Summary `rc.unraid-mcp` refuses to start with: `service start failed: rc.unraid-mcp: FATAL: refusing symlinked appdata path /mnt/user/appdata` The symlink check in `prepare_appdata()` fires on a **legitimate, Unraid-created symlink** produced by the **exclusive share** feature (Primary storage = pool, Secondary storage = none). This is a standard, documented Unraid configuration, so the plugin currently cannot run on such systems at all. ### Environment - Unraid version: 7.3.1 (exclusiv [Read the thread](https://github.com/dinglebear-ai/unraid/issues/370) · 2026-08-12 · closed · external user · 0 comments ### GraphQL validation errors on Unraid 7.3.2 — logs, check_updates, info overview broken # GraphQL validation errors on Unraid 7.x — several tools broken (logs, check_updates, info overview) **Version:** `ghcr.io/jmagar/unraid-mcp:latest` — image version `2.4.0`, revision `359ba7dddce9e324b4c1fdc2a816699ee8da069e`, built 2026-07-16 **Unraid version:** 7.3.2 **Deployment:** Docker on Unraid, bridge network, port 6970 ## Summary Several `unraid_docker` and `unraid_info` actions fail with `GRAPHQL_VALIDATION_FAILED` on Unraid 7.3.2. The queries appear to be written against an older [Read the thread](https://github.com/dinglebear-ai/unraid/issues/312) · 2026-07-30 · closed · external user · 0 comments ### Duplicate hooks entry: manifest.hooks lists hooks/hooks.json which Claude Code auto-loads, breaking hook loading ### Summary The plugin manifest redundantly declares `hooks/hooks.json`, which Claude Code already loads automatically. The duplicate causes hook loading to fail on every load. ### Error ``` Hook load failed: Duplicate hooks file detected: ./hooks/hooks.json resolves to already-loaded file /path/to/plugins/cache/unraid-mcp/unraid-mcp/2.3.5/hooks/hooks.json. The standard hooks/hooks.json is loaded automatically, so manifest.hooks should only reference additional hook files. ``` Surfaces as `1 [Read the thread](https://github.com/dinglebear-ai/unraid/issues/173) · 2026-07-15 · closed · external user · 0 comments ### Plugin manifest has no way to configure TLS for self-signed certs (stock Unraid install fails with FATAL) ### Summary The plugin manifest provides no way to configure TLS behaviour, so the plugin cannot be used against a stock Unraid server (which ships a self-signed cert by default) without hand-editing files outside the plugin. ### Detail In v2.3.5, `plugins/unraid/.mcp.json` passes only: ```json "env": { "UNRAID_MCP_TRANSPORT": "stdio", "UNRAID_API_URL": "${CLAUDE_PLUGIN_OPTION_UNRAID_API_URL}", "UNRAID_API_KEY": "${CLAUDE_PLUGIN_OPTION_UNRAID_API_KEY}" } ``` and `plugins/unraid/.claud [Read the thread](https://github.com/dinglebear-ai/unraid/issues/172) · 2026-07-15 · closed · external user · 0 comments ### Docker: Python version mismatch between builder (3.12) and runtime (3.14) breaks container ## Bug description The runtime stage in the Dockerfile uses a digest-pinned `python` base image that Dependabot recently bumped from Python 3.12 to Python 3.14. The builder stage correctly uses Python 3.12 (`uv:python3.12-bookworm-slim`), so the virtual environment is built for 3.12. When the runtime container starts with Python 3.14, it cannot find any packages because: - Site-packages are at `/app/.venv/lib/python3.12/site-packages/` - Python 3.14 looks in `/app/.venv/lib/python3.14/site-pac [Read the thread](https://github.com/dinglebear-ai/unraid/issues/89) · 2026-06-23 · closed · external user · 0 comments ### Docker healthcheck fails because /health only handles GET while wget --spider sends HEAD ### Summary The Docker image reports `unhealthy` even though the MCP server is running and `GET /health` returns 200. The image-defined Docker healthcheck uses `wget --spider`, which sends a `HEAD /health` request. The application health middleware only handles `GET /health`, so the request falls through to bearer auth and returns `401 Unauthorized` when `UNRAID_MCP_BEARER_TOKEN` is configured. ### Environment - Image: `ghcr.io/jmagar/unraid-mcp:latest` - Image revision label: `454f346036af5 [Read the thread](https://github.com/dinglebear-ai/unraid/issues/31) · 2026-06-09 · closed · external user · 0 comments ### disk shares crashes: "Cannot return null for non-nullable field Share.id" on auto-created shares ## Summary `unraid action=disk subaction=shares` fails outright with: ``` GraphQL API error: Cannot return null for non-nullable field Share.id ``` whenever the Unraid array contains auto-discovered user shares (top-level folders created by containers/`mkdir` that have no `/boot/config/shares/.cfg`). These auto-shares return a `null` `id` from the Unraid API, which the non-nullable `Share.id` selection rejects — making it impossible to enumerate shares as long as any auto-share exists. ## [Read the thread](https://github.com/dinglebear-ai/unraid/issues/29) · 2026-05-29 · closed · external user · 0 comments ### Empty UNRAID_API_URL/UNRAID_API_KEY in .mcp.json shadow ~/.unraid-mcp/.env (credentials never load) ## Summary The bundled `.mcp.json` sets `UNRAID_API_URL=""` and `UNRAID_API_KEY=""` in the server's `env` block. Because `unraid_mcp/config/settings.py` calls `load_dotenv()` with the default `override=False`, these empty strings (now present in the process environment) take precedence over **every** `.env` file on the search path — including the canonical `~/.unraid-mcp/.env`. Result: credentials silently never load and the server reports `CredentialsNotConfiguredError`, defeating the documente [Read the thread](https://github.com/dinglebear-ai/unraid/issues/28) · 2026-05-29 · closed · external user · 0 comments ### Feature: log subcriptions https://github.com/jmagar/unraid-mcp?tab=readme-ov-file#live--11-subactions-websocket-subscriptions I miss an option that can filter out the logs. Like send only logs with warning, wan, error, etc.. and the 2 o 3 previous and later log events for context, so you don't expend much tokens analyzing errors with AI. [Read the thread](https://github.com/dinglebear-ai/unraid/issues/26) · 2026-04-16 · closed · external user · 0 comments The remaining reports are on [the project's issue tracker](https://github.com/jmagar/unraid-mcp/issues).