forked from HomeLab/unraid-mcp
184b8aca1c
**Critical Fixes (7 issues):**
- Fix GraphQL schema field names in users tool (role→roles, remove email)
- Fix GraphQL mutation signatures (addUserInput, deleteUser input)
- Fix dict(None) TypeError guards in users tool (use `or {}` pattern)
- Fix FastAPI version constraint (0.116.1→0.115.0)
- Fix WebSocket SSL context handling (support CA bundles, bool, and None)
- Fix critical disk threshold treated as warning (split counters)
**High Priority Fixes (11 issues):**
- Fix Docker update/remove action response field mapping
- Fix path traversal vulnerability in log validation (normalize paths)
- Fix deleteApiKeys validation (check response before success)
- Fix rclone create_remote validation (check response)
- Fix keys input_data type annotation (dict[str, Any])
- Fix VM domain/domains fallback restoration
**Changes by file:**
- unraid_mcp/tools/docker.py: Response field mapping
- unraid_mcp/tools/info.py: Split critical/warning counters
- unraid_mcp/tools/storage.py: Path normalization for traversal protection
- unraid_mcp/tools/users.py: GraphQL schema + null handling
- unraid_mcp/tools/keys.py: Validation + type annotations
- unraid_mcp/tools/rclone.py: Response validation
- unraid_mcp/tools/virtualization.py: Domain fallback
- unraid_mcp/subscriptions/manager.py: SSL context creation
- pyproject.toml: FastAPI version fix
- tests/*: New tests for all fixes
**Review threads resolved:**
PRRT_kwDOO6Hdxs5uu70L, PRRT_kwDOO6Hdxs5uu70O, PRRT_kwDOO6Hdxs5uu70V,
PRRT_kwDOO6Hdxs5uu70e, PRRT_kwDOO6Hdxs5uu70i, PRRT_kwDOO6Hdxs5uu7zn,
PRRT_kwDOO6Hdxs5uu7z_, PRRT_kwDOO6Hdxs5uu7sI, PRRT_kwDOO6Hdxs5uu7sJ,
PRRT_kwDOO6Hdxs5uu7sK, PRRT_kwDOO6Hdxs5uu7Tk, PRRT_kwDOO6Hdxs5uu7Tn,
PRRT_kwDOO6Hdxs5uu7Tr, PRRT_kwDOO6Hdxs5uu7Ts, PRRT_kwDOO6Hdxs5uu7Tu,
PRRT_kwDOO6Hdxs5uu7Tv, PRRT_kwDOO6Hdxs5uu7Tw, PRRT_kwDOO6Hdxs5uu7Tx
All tests passing.
Co-authored-by: docker-fixer <agent@pr-fixes>
Co-authored-by: info-fixer <agent@pr-fixes>
Co-authored-by: storage-fixer <agent@pr-fixes>
Co-authored-by: users-fixer <agent@pr-fixes>
Co-authored-by: config-fixer <agent@pr-fixes>
Co-authored-by: websocket-fixer <agent@pr-fixes>
Co-authored-by: keys-rclone-fixer <agent@pr-fixes>
Co-authored-by: vm-fixer <agent@pr-fixes>
Unraid API Skill
Query and monitor Unraid servers via the GraphQL API.
What's Included
This skill provides complete access to all 27 read-only Unraid GraphQL API endpoints.
Files
skills/unraid/
├── SKILL.md # Main skill documentation
├── README.md # This file
├── scripts/
│ └── unraid-query.sh # GraphQL query helper script
├── examples/
│ ├── monitoring-dashboard.sh # Complete system dashboard
│ ├── disk-health.sh # Disk temperature & health check
│ └── read-logs.sh # Log file reader
└── references/
├── api-reference.md # Complete API documentation
└── quick-reference.md # Common queries cheat sheet
Quick Start
-
Set your credentials:
export UNRAID_URL="https://your-unraid-server/graphql" export UNRAID_API_KEY="your-api-key" -
Run a query:
cd skills/unraid ./scripts/unraid-query.sh -q "{ online }" -
Run examples:
./examples/monitoring-dashboard.sh ./examples/disk-health.sh
Triggers
This skill activates when you mention:
- "check Unraid"
- "monitor Unraid"
- "Unraid API"
- "Unraid disk temperatures"
- "Unraid array status"
- "read Unraid logs"
- And more Unraid-related monitoring tasks
Features
- 27 working endpoints - All read-only queries documented
- Helper script - Easy CLI interface for GraphQL queries
- Example scripts - Ready-to-use monitoring scripts
- Complete reference - Detailed documentation with examples
- Quick reference - Common queries cheat sheet
Endpoints Covered
System & Monitoring
- System info (CPU, OS, hardware)
- Real-time metrics (CPU %, memory %)
- Configuration & settings
- Log files (list & read)
Storage
- Array status & disks
- All physical disks (including cache/USB)
- Network shares
- Parity check status
Virtualization
- Docker containers
- Virtual machines
Power & Alerts
- UPS devices
- System notifications
Administration
- API key management
- User & authentication
- Server registration
- UI customization
Requirements
- Unraid 7.2+ (GraphQL API)
- API Key with Viewer role
- jq for JSON parsing (usually pre-installed)
- curl for HTTP requests
Getting an API Key
- Log in to Unraid WebGUI
- Settings → Management Access → API Keys
- Click "Create API Key"
- Name: "monitoring" (or whatever you like)
- Role: Select "Viewer" (read-only)
- Copy the generated key
Documentation
- SKILL.md - Start here for task-oriented guidance
- references/api-reference.md - Complete endpoint reference
- references/quick-reference.md - Quick query examples
Examples
System Status
./scripts/unraid-query.sh -q "{ online metrics { cpu { percentTotal } } }"
Disk Health
./examples/disk-health.sh
Complete Dashboard
./examples/monitoring-dashboard.sh
Read Logs
./examples/read-logs.sh syslog 20
Notes
- All sizes are in kilobytes
- Temperatures are in Celsius
- Docker container logs are not accessible via API (use SSH)
- Poll no faster than every 5 seconds to avoid server load
Version
- Skill Version: 1.0.0
- API Version: Unraid 7.2 GraphQL
- Tested: 2026-01-21
- Endpoints: 27 working read-only queries