cc24f1ec62
- ApiKeyVerifier(TokenVerifier) — validates Authorization: Bearer <key> against UNRAID_MCP_API_KEY; guards against empty-key bypass - _build_auth() replaces module-level _build_google_auth() call: returns MultiAuth(server=google, verifiers=[api_key]) when both set, GoogleProvider alone, ApiKeyVerifier alone, or None - settings.py: add UNRAID_MCP_API_KEY + is_api_key_auth_configured() + api_key_auth_enabled in get_config_summary() - run_server(): improved auth status logging for all three states - tests/test_api_key_auth.py: 9 tests covering verifier + _build_auth - .env.example: add UNRAID_MCP_API_KEY section - docs/GOOGLE_OAUTH.md: add API Key section - README.md / CLAUDE.md: rename section, document both auth methods - Fix pre-existing: test_health.py patched cache_middleware/error_middleware now match renamed _cache_middleware/_error_middleware in server.py
3.3 KiB
Unraid MCP — Troubleshooting Guide
Credentials Not Configured
Error: CredentialsNotConfiguredError or message containing ~/.unraid-mcp/.env
Fix: Run setup to configure credentials interactively:
unraid(action="health", subaction="setup")
This writes UNRAID_API_URL and UNRAID_API_KEY to ~/.unraid-mcp/.env. Re-run at any time to update or rotate credentials.
Connection Failed / API Unreachable
Symptoms: Timeout, connection refused, network error
Diagnostic steps:
- Test basic connectivity:
unraid(action="health", subaction="test_connection")
- Full diagnostic report:
unraid(action="health", subaction="diagnose")
-
Check that
UNRAID_API_URLin~/.unraid-mcp/.envpoints to the correct Unraid GraphQL endpoint. -
Verify the API key has the required roles. Get a new key: Unraid UI → Settings → Management Access → API Keys → Create (select "Viewer" role for read-only, or appropriate roles for mutations).
Invalid Action / Subaction
Error: Invalid action 'X' or Invalid subaction 'X' for action 'Y'
Fix: Check the domain table in SKILL.md for the exact action= and subaction= strings. Common mistakes:
| Wrong | Correct |
|---|---|
action="info" |
action="system" |
action="notifications" |
action="notification" |
action="keys" |
action="key" |
action="plugins" |
action="plugin" |
action="settings" |
action="setting" |
subaction="unread" |
subaction="mark_unread" |
Destructive Action Blocked
Error: Action 'X' was not confirmed. Re-run with confirm=True to bypass elicitation.
Fix: Add confirm=True to the call:
unraid(action="array", subaction="stop_array", confirm=True)
unraid(action="vm", subaction="force_stop", vm_id="<id>", confirm=True)
See the Destructive Actions table in SKILL.md for the full list.
Live Subscription Returns "Connecting"
Symptoms: unraid(action="live", ...) returns {"status": "connecting"}
Explanation: The persistent WebSocket subscription has not yet received its first event. Retry in a moment.
Known issue: live/array_state uses arraySubscription which has a known Unraid API bug (returns null for a non-nullable field). This subscription will always show "connecting."
Event-driven subscriptions (live/notifications_overview, live/owner, live/server_status, live/ups_status) only populate when the server emits a change event. If the server is idle, these may never populate during a session.
Workaround for array state: Use unraid(action="system", subaction="array") for a synchronous snapshot instead.
Rate Limit Exceeded
Limit: 100 requests / 10 seconds
Symptoms: HTTP 429 or rate limit error
Fix: Space out requests. Avoid polling in tight loops. Use live/ subscriptions for real-time data instead of polling system/metrics repeatedly.
Log Path Rejected
Error: Invalid log path
Valid log path prefixes: /var/log/, /boot/logs/, /mnt/
Use unraid(action="disk", subaction="log_files") to list available logs before reading.
Container Logs Not Available
Docker container stdout/stderr are not accessible via the Unraid API. SSH to the Unraid server and use docker logs <container> directly.