pod
Other formats agents might prefer:
markdownjsonllms.txt

Agent? You probably want markdown or json, or Pod over MCP.

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.

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 · 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 · 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 · 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:

"UNRAID_VERIFY_SSL": "true"

it overrides the .env value. The MCP server then falls back to Py

Read the thread · 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 · 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 · 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://<SERVER>: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.

<details><summary>diff</summary>

```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

<!-- upstream-schema-sha256: dd453b0652ac5261385a0ae49c3d4dcf8f53a40052c1fa4f1c555359c9f6ff23 -->

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 · 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 · 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 · 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/<name>.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 · 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 · 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 · 2026-04-16 · closed · external user · 0 comments

The remaining reports are on the project's issue tracker.