mirror of
https://github.com/jmagar/unraid-mcp.git
synced 2026-03-23 12:39:24 -07:00
fix: address all 17 PR review comments
Resolves review threads: - PRRT_kwDOO6Hdxs50fewG (setup.py): non-eliciting clients now return True from elicit_reset_confirmation so they can reconfigure without being blocked - PRRT_kwDOO6Hdxs50fewM (test-tools.sh): add notification/recalculate smoke test - PRRT_kwDOO6Hdxs50fewP (test-tools.sh): add system/array smoke test - PRRT_kwDOO6Hdxs50fewT (resources.py): surface manager error state instead of reporting 'connecting' for permanently failed subscriptions - PRRT_kwDOO6Hdxs50feAj (resources.py): use is not None check for empty cached dicts - PRRT_kwDOO6Hdxs50fewY (integration tests): remove duplicate snapshot-registration tests already covered in test_resources.py - PRRT_kwDOO6Hdxs50fewe (test_resources.py): replace brittle import-detail test with behavior tests for connecting/error states - PRRT_kwDOO6Hdxs50fewh (test_customization.py): strengthen public_theme assertion - PRRT_kwDOO6Hdxs50fewk (test_customization.py): strengthen theme assertion - PRRT_kwDOO6Hdxs50fewo (__init__.py): correct subaction count ~88 -> ~107 - PRRT_kwDOO6Hdxs50fewx (test_oidc.py): assert providers list value directly - PRRT_kwDOO6Hdxs50fewz (unraid.py): remove unreachable raise after vm handler - PRRT_kwDOO6Hdxs50few2 (unraid.py): remove unreachable raise after docker handler - PRRT_kwDOO6Hdxs50fev8 (CLAUDE.md): replace legacy 15-tool table with unified unraid action/subaction table - PRRT_kwDOO6Hdxs50fev_ (test_oidc.py): assert providers + defaultAllowedOrigins - PRRT_kwDOO6Hdxs50feAz (CLAUDE.md): update tool categories to unified API shape - PRRT_kwDOO6Hdxs50feBE (CLAUDE.md/setup.py): update unraid_health refs to unraid(action=health, subaction=setup)
This commit is contained in:
Jacob Magar
@@ -1,210 +1,292 @@
|
||||
---
|
||||
name: unraid
|
||||
description: "Query and monitor Unraid servers via the GraphQL API. Use when the user asks to 'check Unraid', 'monitor Unraid', 'Unraid API', 'get Unraid status', 'check disk temperatures', 'read Unraid logs', 'list Unraid shares', 'Unraid array status', 'Unraid containers', 'Unraid VMs', or mentions Unraid system monitoring, disk health, parity checks, or server status."
|
||||
description: "This skill should be used when the user mentions Unraid, asks to check server health, monitor array or disk status, list or restart Docker containers, start or stop VMs, read system logs, check parity status, view notifications, manage API keys, configure rclone remotes, check UPS or power status, get live CPU or memory data, force stop a VM, check disk temperatures, or perform any operation on an Unraid NAS server. Also use when the user needs to set up or configure Unraid MCP credentials."
|
||||
---
|
||||
|
||||
# Unraid API Skill
|
||||
# Unraid MCP Skill
|
||||
|
||||
**⚠️ MANDATORY SKILL INVOCATION ⚠️**
|
||||
Use the single `unraid` MCP tool with `action` (domain) + `subaction` (operation) for all Unraid operations.
|
||||
|
||||
**YOU MUST invoke this skill (NOT optional) when the user mentions ANY of these triggers:**
|
||||
- "Unraid status", "disk health", "array status"
|
||||
- "Unraid containers", "VMs on Unraid", "Unraid logs"
|
||||
- "check Unraid", "Unraid monitoring", "server health"
|
||||
- Any mention of Unraid servers or system monitoring
|
||||
## Setup
|
||||
|
||||
**Failure to invoke this skill when triggers occur violates your operational requirements.**
|
||||
First time? Run setup to configure credentials:
|
||||
|
||||
Query and monitor Unraid servers using the GraphQL API. Access all 27 read-only endpoints for system monitoring, disk health, logs, containers, VMs, and more.
|
||||
|
||||
## Quick Start
|
||||
|
||||
Set your Unraid server credentials:
|
||||
|
||||
```bash
|
||||
export UNRAID_URL="https://your-unraid-server/graphql"
|
||||
export UNRAID_API_KEY="your-api-key"
|
||||
```
|
||||
unraid(action="health", subaction="setup")
|
||||
```
|
||||
|
||||
**Get API Key:** Settings → Management Access → API Keys → Create (select "Viewer" role)
|
||||
Credentials are stored at `~/.unraid-mcp/.env`. Re-run `setup` any time to update or verify.
|
||||
|
||||
Use the helper script for any query:
|
||||
## Calling Convention
|
||||
|
||||
```bash
|
||||
./scripts/unraid-query.sh -q "{ online }"
|
||||
```
|
||||
unraid(action="<domain>", subaction="<operation>", [additional params])
|
||||
```
|
||||
|
||||
Or run example scripts:
|
||||
|
||||
```bash
|
||||
./scripts/dashboard.sh # Complete multi-server dashboard
|
||||
./examples/disk-health.sh # Disk temperatures & health
|
||||
./examples/read-logs.sh syslog 20 # Read system logs
|
||||
**Examples:**
|
||||
```
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### GraphQL API Structure
|
||||
|
||||
Unraid 7.2+ uses GraphQL (not REST). Key differences:
|
||||
- **Single endpoint:** `/graphql` for all queries
|
||||
- **Request exactly what you need:** Specify fields in query
|
||||
- **Strongly typed:** Use introspection to discover fields
|
||||
- **No container logs:** Docker container output logs not accessible
|
||||
|
||||
### Two Resources for Stats
|
||||
|
||||
- **`info`** - Static hardware specs (CPU model, cores, OS version)
|
||||
- **`metrics`** - Real-time usage (CPU %, memory %, current load)
|
||||
|
||||
Always use `metrics` for monitoring, `info` for specifications.
|
||||
|
||||
## Common Tasks
|
||||
|
||||
### System Monitoring
|
||||
|
||||
**Check if server is online:**
|
||||
```bash
|
||||
./scripts/unraid-query.sh -q "{ online }"
|
||||
```
|
||||
|
||||
**Get CPU and memory usage:**
|
||||
```bash
|
||||
./scripts/unraid-query.sh -q "{ metrics { cpu { percentTotal } memory { used total percentTotal } } }"
|
||||
```
|
||||
|
||||
**Complete dashboard:**
|
||||
```bash
|
||||
./scripts/dashboard.sh
|
||||
```
|
||||
|
||||
### Disk Management
|
||||
|
||||
**Check disk health and temperatures:**
|
||||
```bash
|
||||
./examples/disk-health.sh
|
||||
```
|
||||
|
||||
**Get array status:**
|
||||
```bash
|
||||
./scripts/unraid-query.sh -q "{ array { state parityCheckStatus { status progress errors } } }"
|
||||
```
|
||||
|
||||
**List all physical disks (including cache/USB):**
|
||||
```bash
|
||||
./scripts/unraid-query.sh -q "{ disks { name } }"
|
||||
```
|
||||
|
||||
### Storage Shares
|
||||
|
||||
**List network shares:**
|
||||
```bash
|
||||
./scripts/unraid-query.sh -q "{ shares { name comment } }"
|
||||
```
|
||||
|
||||
### Logs
|
||||
|
||||
**List available logs:**
|
||||
```bash
|
||||
./scripts/unraid-query.sh -q "{ logFiles { name size modifiedAt } }"
|
||||
```
|
||||
|
||||
**Read log content:**
|
||||
```bash
|
||||
./examples/read-logs.sh syslog 20
|
||||
```
|
||||
|
||||
### Containers & VMs
|
||||
|
||||
**List Docker containers:**
|
||||
```bash
|
||||
./scripts/unraid-query.sh -q "{ docker { containers { names image state status } } }"
|
||||
```
|
||||
|
||||
**List VMs:**
|
||||
```bash
|
||||
./scripts/unraid-query.sh -q "{ vms { domain { name state } } }"
|
||||
```
|
||||
|
||||
**Note:** Container output logs are NOT accessible via API. Use `docker logs` via SSH.
|
||||
|
||||
### Notifications
|
||||
|
||||
**Get notification counts:**
|
||||
```bash
|
||||
./scripts/unraid-query.sh -q "{ notifications { overview { unread { info warning alert total } } } }"
|
||||
```
|
||||
|
||||
## Helper Script Usage
|
||||
|
||||
The `scripts/unraid-query.sh` helper supports:
|
||||
|
||||
```bash
|
||||
# Basic usage
|
||||
./scripts/unraid-query.sh -u URL -k API_KEY -q "QUERY"
|
||||
|
||||
# Use environment variables
|
||||
export UNRAID_URL="https://unraid.local/graphql"
|
||||
export UNRAID_API_KEY="your-key"
|
||||
./scripts/unraid-query.sh -q "{ online }"
|
||||
|
||||
# Format options
|
||||
-f json # Raw JSON (default)
|
||||
-f pretty # Pretty-printed JSON
|
||||
-f raw # Just the data (no wrapper)
|
||||
```
|
||||
|
||||
## Additional Resources
|
||||
|
||||
### Reference Files
|
||||
|
||||
For detailed documentation, consult:
|
||||
- **`references/endpoints.md`** - Complete list of all 27 API endpoints
|
||||
- **`references/troubleshooting.md`** - Common errors and solutions
|
||||
- **`references/api-reference.md`** - Detailed field documentation
|
||||
|
||||
### Helper Scripts
|
||||
|
||||
- **`scripts/unraid-query.sh`** - Main GraphQL query tool
|
||||
- **`scripts/dashboard.sh`** - Automated multi-server inventory reporter
|
||||
|
||||
## Quick Command Reference
|
||||
|
||||
```bash
|
||||
# System status
|
||||
./scripts/unraid-query.sh -q "{ online metrics { cpu { percentTotal } } }"
|
||||
|
||||
# Disk health
|
||||
./examples/disk-health.sh
|
||||
|
||||
# Array status
|
||||
./scripts/unraid-query.sh -q "{ array { state } }"
|
||||
|
||||
# Read logs
|
||||
./examples/read-logs.sh syslog 20
|
||||
|
||||
# Complete dashboard
|
||||
./scripts/dashboard.sh
|
||||
|
||||
# List shares
|
||||
./scripts/unraid-query.sh -q "{ shares { name } }"
|
||||
|
||||
# List containers
|
||||
./scripts/unraid-query.sh -q "{ docker { containers { names state } } }"
|
||||
unraid(action="system", subaction="overview")
|
||||
unraid(action="docker", subaction="list")
|
||||
unraid(action="health", subaction="check")
|
||||
unraid(action="array", subaction="parity_status")
|
||||
unraid(action="disk", subaction="disks")
|
||||
unraid(action="vm", subaction="list")
|
||||
unraid(action="notification", subaction="overview")
|
||||
unraid(action="live", subaction="cpu")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Agent Tool Usage Requirements
|
||||
## All Domains and Subactions
|
||||
|
||||
**CRITICAL:** When invoking scripts from this skill via the zsh-tool, **ALWAYS use `pty: true`**.
|
||||
### `system` — Server Information
|
||||
| Subaction | Description |
|
||||
|-----------|-------------|
|
||||
| `overview` | Complete system summary (recommended starting point) |
|
||||
| `server` | Hostname, version, uptime |
|
||||
| `servers` | All known Unraid servers |
|
||||
| `array` | Array status and disk list |
|
||||
| `network` | Network interfaces and config |
|
||||
| `registration` | License and registration status |
|
||||
| `variables` | Environment variables |
|
||||
| `metrics` | Real-time CPU, memory, I/O usage |
|
||||
| `services` | Running services status |
|
||||
| `display` | Display settings |
|
||||
| `config` | System configuration |
|
||||
| `online` | Quick online status check |
|
||||
| `owner` | Server owner information |
|
||||
| `settings` | User settings and preferences |
|
||||
| `flash` | USB flash drive details |
|
||||
| `ups_devices` | List all UPS devices |
|
||||
| `ups_device` | Single UPS device (requires `device_id`) |
|
||||
| `ups_config` | UPS configuration |
|
||||
|
||||
Without PTY mode, command output will not be visible even though commands execute successfully.
|
||||
### `health` — Diagnostics
|
||||
| Subaction | Description |
|
||||
|-----------|-------------|
|
||||
| `check` | Comprehensive health check — connectivity, array, disks, containers, VMs, resources |
|
||||
| `test_connection` | Test API connectivity and authentication |
|
||||
| `diagnose` | Detailed diagnostic report with troubleshooting recommendations |
|
||||
| `setup` | Configure credentials interactively (stores to `~/.unraid-mcp/.env`) |
|
||||
|
||||
**Correct invocation pattern:**
|
||||
```typescript
|
||||
<invoke name="mcp__plugin_zsh-tool_zsh-tool__zsh">
|
||||
<parameter name="command">./skills/SKILL_NAME/scripts/SCRIPT.sh [args]</parameter>
|
||||
<parameter name="pty">true</parameter>
|
||||
</invoke>
|
||||
### `array` — Array & Parity
|
||||
| Subaction | Description |
|
||||
|-----------|-------------|
|
||||
| `parity_status` | Current parity check progress and status |
|
||||
| `parity_history` | Historical parity check results |
|
||||
| `parity_start` | Start a parity check |
|
||||
| `parity_pause` | Pause a running parity check |
|
||||
| `parity_resume` | Resume a paused parity check |
|
||||
| `parity_cancel` | Cancel a running parity check |
|
||||
| `start_array` | Start the array |
|
||||
| `stop_array` | ⚠️ Stop the array (requires `confirm=True`) |
|
||||
| `add_disk` | Add a disk to the array (requires `slot`, `id`) |
|
||||
| `remove_disk` | ⚠️ Remove a disk (requires `slot`, `confirm=True`) |
|
||||
| `mount_disk` | Mount a disk |
|
||||
| `unmount_disk` | Unmount a disk |
|
||||
| `clear_disk_stats` | ⚠️ Clear disk statistics (requires `confirm=True`) |
|
||||
|
||||
### `disk` — Storage & Logs
|
||||
| Subaction | Description |
|
||||
|-----------|-------------|
|
||||
| `shares` | List network shares |
|
||||
| `disks` | All physical disks with health and temperatures |
|
||||
| `disk_details` | Detailed info for a specific disk (requires `disk_id`) |
|
||||
| `log_files` | List available log files |
|
||||
| `logs` | Read log content (requires `path`; optional `lines`) |
|
||||
| `flash_backup` | ⚠️ Trigger a flash backup (requires `confirm=True`) |
|
||||
|
||||
### `docker` — Containers
|
||||
| Subaction | Description |
|
||||
|-----------|-------------|
|
||||
| `list` | All containers with status, image, state |
|
||||
| `details` | Single container details (requires container identifier) |
|
||||
| `start` | Start a container (requires container identifier) |
|
||||
| `stop` | Stop a container (requires container identifier) |
|
||||
| `restart` | Restart a container (requires container identifier) |
|
||||
| `networks` | List Docker networks |
|
||||
| `network_details` | Details for a specific network (requires `network_id`) |
|
||||
|
||||
**Container Identification:** Name, ID, or partial name (fuzzy match supported).
|
||||
|
||||
### `vm` — Virtual Machines
|
||||
| Subaction | Description |
|
||||
|-----------|-------------|
|
||||
| `list` | All VMs with state |
|
||||
| `details` | Single VM details (requires `vm_id`) |
|
||||
| `start` | Start a VM (requires `vm_id`) |
|
||||
| `stop` | Gracefully stop a VM (requires `vm_id`) |
|
||||
| `pause` | Pause a VM (requires `vm_id`) |
|
||||
| `resume` | Resume a paused VM (requires `vm_id`) |
|
||||
| `reboot` | Reboot a VM (requires `vm_id`) |
|
||||
| `force_stop` | ⚠️ Force stop a VM (requires `vm_id`, `confirm=True`) |
|
||||
| `reset` | ⚠️ Hard reset a VM (requires `vm_id`, `confirm=True`) |
|
||||
|
||||
### `notification` — Notifications
|
||||
| Subaction | Description |
|
||||
|-----------|-------------|
|
||||
| `overview` | Notification counts (unread, archived by type) |
|
||||
| `list` | List notifications (optional `filter`, `limit`, `offset`) |
|
||||
| `mark_unread` | Mark a notification as unread (requires `notification_id`) |
|
||||
| `create` | Create a notification (requires `title`, `subject`, `description`, `importance`) |
|
||||
| `archive` | Archive a notification (requires `notification_id`) |
|
||||
| `delete` | ⚠️ Delete a notification (requires `notification_id`, `notification_type`, `confirm=True`) |
|
||||
| `delete_archived` | ⚠️ Delete all archived (requires `confirm=True`) |
|
||||
| `archive_all` | Archive all unread notifications |
|
||||
| `archive_many` | Archive multiple (requires `ids` list) |
|
||||
| `unarchive_many` | Unarchive multiple (requires `ids` list) |
|
||||
| `unarchive_all` | Unarchive all archived notifications |
|
||||
| `recalculate` | Recalculate notification counts |
|
||||
|
||||
### `key` — API Keys
|
||||
| Subaction | Description |
|
||||
|-----------|-------------|
|
||||
| `list` | All API keys |
|
||||
| `get` | Single key details (requires `key_id`) |
|
||||
| `create` | Create a new key (requires `name`, `roles`) |
|
||||
| `update` | Update a key (requires `key_id`) |
|
||||
| `delete` | ⚠️ Delete a key (requires `key_id`, `confirm=True`) |
|
||||
| `add_role` | Add a role to a key (requires `key_id`, `role`) |
|
||||
| `remove_role` | Remove a role from a key (requires `key_id`, `role`) |
|
||||
|
||||
### `plugin` — Plugins
|
||||
| Subaction | Description |
|
||||
|-----------|-------------|
|
||||
| `list` | All installed plugins |
|
||||
| `add` | Install plugins (requires `names` — list of plugin names) |
|
||||
| `remove` | ⚠️ Uninstall plugins (requires `names` — list of plugin names, `confirm=True`) |
|
||||
|
||||
### `rclone` — Cloud Storage
|
||||
| Subaction | Description |
|
||||
|-----------|-------------|
|
||||
| `list_remotes` | List configured rclone remotes |
|
||||
| `config_form` | Get configuration form for a remote type |
|
||||
| `create_remote` | Create a new remote (requires `name`, `type`, `fields`) |
|
||||
| `delete_remote` | ⚠️ Delete a remote (requires `name`, `confirm=True`) |
|
||||
|
||||
### `setting` — System Settings
|
||||
| Subaction | Description |
|
||||
|-----------|-------------|
|
||||
| `update` | Update system settings (requires `settings` object) |
|
||||
| `configure_ups` | ⚠️ Configure UPS settings (requires `confirm=True`) |
|
||||
|
||||
### `customization` — Theme & Appearance
|
||||
| Subaction | Description |
|
||||
|-----------|-------------|
|
||||
| `theme` | Current theme settings |
|
||||
| `public_theme` | Public-facing theme |
|
||||
| `is_initial_setup` | Check if initial setup is complete |
|
||||
| `sso_enabled` | Check SSO status |
|
||||
| `set_theme` | Update theme (requires theme parameters) |
|
||||
|
||||
### `oidc` — SSO / OpenID Connect
|
||||
| Subaction | Description |
|
||||
|-----------|-------------|
|
||||
| `providers` | List configured OIDC providers |
|
||||
| `provider` | Single provider details (requires `provider_id`) |
|
||||
| `configuration` | OIDC configuration |
|
||||
| `public_providers` | Public-facing provider list |
|
||||
| `validate_session` | Validate current SSO session |
|
||||
|
||||
### `user` — Current User
|
||||
| Subaction | Description |
|
||||
|-----------|-------------|
|
||||
| `me` | Current authenticated user info |
|
||||
|
||||
### `live` — Real-Time Subscriptions
|
||||
These use persistent WebSocket connections. Returns a "connecting" placeholder on the first call — retry momentarily for live data.
|
||||
|
||||
| Subaction | Description |
|
||||
|-----------|-------------|
|
||||
| `cpu` | Live CPU utilization |
|
||||
| `memory` | Live memory usage |
|
||||
| `cpu_telemetry` | Detailed CPU telemetry |
|
||||
| `array_state` | Live array state changes |
|
||||
| `parity_progress` | Live parity check progress |
|
||||
| `ups_status` | Live UPS status |
|
||||
| `notifications_overview` | Live notification counts |
|
||||
| `owner` | Live owner info |
|
||||
| `server_status` | Live server status |
|
||||
| `log_tail` | Live log tail stream |
|
||||
| `notification_feed` | Live notification feed |
|
||||
|
||||
---
|
||||
|
||||
## Destructive Actions
|
||||
|
||||
All require `confirm=True` as an explicit parameter. Without it, the action is blocked and elicitation is triggered.
|
||||
|
||||
| Domain | Subaction | Risk |
|
||||
|--------|-----------|------|
|
||||
| `array` | `stop_array` | Stops array while containers/VMs may use shares |
|
||||
| `array` | `remove_disk` | Removes disk from array |
|
||||
| `array` | `clear_disk_stats` | Clears disk statistics permanently |
|
||||
| `vm` | `force_stop` | Hard kills VM without graceful shutdown |
|
||||
| `vm` | `reset` | Hard resets VM |
|
||||
| `notification` | `delete` | Permanently deletes a notification |
|
||||
| `notification` | `delete_archived` | Permanently deletes all archived notifications |
|
||||
| `rclone` | `delete_remote` | Removes a cloud storage remote |
|
||||
| `key` | `delete` | Permanently deletes an API key |
|
||||
| `disk` | `flash_backup` | Triggers flash backup operation |
|
||||
| `setting` | `configure_ups` | Modifies UPS configuration |
|
||||
| `plugin` | `remove` | Uninstalls a plugin |
|
||||
|
||||
---
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### First-time setup
|
||||
```
|
||||
unraid(action="health", subaction="setup")
|
||||
unraid(action="health", subaction="check")
|
||||
```
|
||||
|
||||
### System health overview
|
||||
```
|
||||
unraid(action="system", subaction="overview")
|
||||
unraid(action="health", subaction="check")
|
||||
```
|
||||
|
||||
### Container management
|
||||
```
|
||||
unraid(action="docker", subaction="list")
|
||||
unraid(action="docker", subaction="details", container_id="plex")
|
||||
unraid(action="docker", subaction="restart", container_id="sonarr")
|
||||
```
|
||||
|
||||
### Array and disk status
|
||||
```
|
||||
unraid(action="array", subaction="parity_status")
|
||||
unraid(action="disk", subaction="disks")
|
||||
unraid(action="system", subaction="array")
|
||||
```
|
||||
|
||||
### Read logs
|
||||
```
|
||||
unraid(action="disk", subaction="log_files")
|
||||
unraid(action="disk", subaction="logs", path="syslog", lines=50)
|
||||
```
|
||||
|
||||
### Live monitoring
|
||||
```
|
||||
unraid(action="live", subaction="cpu")
|
||||
unraid(action="live", subaction="memory")
|
||||
unraid(action="live", subaction="array_state")
|
||||
```
|
||||
|
||||
### VM operations
|
||||
```
|
||||
unraid(action="vm", subaction="list")
|
||||
unraid(action="vm", subaction="start", vm_id="<id>")
|
||||
unraid(action="vm", subaction="force_stop", vm_id="<id>", confirm=True)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- **Rate limit:** 100 requests / 10 seconds
|
||||
- **Log path validation:** Only `/var/log/`, `/boot/logs/`, `/mnt/` prefixes accepted
|
||||
- **Container logs:** Docker container stdout/stderr are NOT accessible via API — use SSH + `docker logs`
|
||||
- **`arraySubscription`:** Known Unraid API bug — `live/array_state` may show "connecting" indefinitely
|
||||
- **Event-driven subs** (`notifications_overview`, `owner`, `server_status`, `ups_status`): Only populate cache on first real server event
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
> **⚠️ DEVELOPER REFERENCE ONLY** — This file documents the raw GraphQL API schema for development and maintenance purposes (adding new queries/mutations). Do NOT use these curl/GraphQL examples for MCP tool usage. Use `unraid(action=..., subaction=...)` calls instead. See `SKILL.md` for the correct calling convention.
|
||||
|
||||
# Unraid API - Complete Reference Guide
|
||||
|
||||
**Tested on:** Unraid 7.2 x86_64
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
> **⚠️ DEVELOPER REFERENCE ONLY** — This file documents raw GraphQL endpoints for development purposes. For MCP tool usage, use `unraid(action=..., subaction=...)` calls as documented in `SKILL.md`.
|
||||
|
||||
# Unraid API Endpoints Reference
|
||||
|
||||
Complete list of available GraphQL read-only endpoints in Unraid 7.2+.
|
||||
|
||||
@@ -1,3 +1,5 @@
|
||||
> **⚠️ DEVELOPER REFERENCE ONLY** — Full GraphQL SDL from live API introspection. Use this to verify field names and types when adding new queries/mutations to the MCP server. Not for runtime agent usage.
|
||||
|
||||
"""
|
||||
Indicates exactly one field must be supplied and this field must not be `null`.
|
||||
"""
|
||||
|
||||
@@ -1,219 +1,115 @@
|
||||
# Unraid API Quick Reference
|
||||
# Unraid MCP — Quick Reference
|
||||
|
||||
Quick reference for the most common Unraid GraphQL API queries.
|
||||
All operations use: `unraid(action="<domain>", subaction="<operation>", [params])`
|
||||
|
||||
## Setup
|
||||
## Most Common Operations
|
||||
|
||||
```bash
|
||||
# Set environment variables
|
||||
export UNRAID_URL="https://your-unraid-server/graphql"
|
||||
export UNRAID_API_KEY="your-api-key-here"
|
||||
|
||||
# Or use the helper script directly
|
||||
./scripts/unraid-query.sh -u "$UNRAID_URL" -k "$UNRAID_API_KEY" -q "{ online }"
|
||||
### Health & Status
|
||||
```
|
||||
unraid(action="health", subaction="setup") # First-time credential setup
|
||||
unraid(action="health", subaction="check") # Full health check
|
||||
unraid(action="health", subaction="test_connection") # Quick connectivity test
|
||||
unraid(action="system", subaction="overview") # Complete server summary
|
||||
unraid(action="system", subaction="metrics") # CPU / RAM / I/O usage
|
||||
unraid(action="system", subaction="online") # Online status
|
||||
```
|
||||
|
||||
## Common Queries
|
||||
|
||||
### System Status
|
||||
```graphql
|
||||
{
|
||||
online
|
||||
metrics {
|
||||
cpu { percentTotal }
|
||||
memory { total used free percentTotal }
|
||||
}
|
||||
}
|
||||
### Array & Disks
|
||||
```
|
||||
unraid(action="system", subaction="array") # Array status overview
|
||||
unraid(action="disk", subaction="disks") # All disks with temps & health
|
||||
unraid(action="array", subaction="parity_status") # Current parity check
|
||||
unraid(action="array", subaction="parity_history") # Past parity results
|
||||
unraid(action="array", subaction="parity_start") # Start parity check
|
||||
unraid(action="array", subaction="stop_array", confirm=True) # ⚠️ Stop array
|
||||
```
|
||||
|
||||
### Array Status
|
||||
```graphql
|
||||
{
|
||||
array {
|
||||
state
|
||||
parityCheckStatus { status progress errors }
|
||||
}
|
||||
}
|
||||
### Logs
|
||||
```
|
||||
|
||||
### Disk List with Temperatures
|
||||
```graphql
|
||||
{
|
||||
array {
|
||||
disks {
|
||||
name
|
||||
device
|
||||
temp
|
||||
status
|
||||
fsSize
|
||||
fsFree
|
||||
isSpinning
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### All Physical Disks (including USB/SSDs)
|
||||
```graphql
|
||||
{
|
||||
disks {
|
||||
id
|
||||
name
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Network Shares
|
||||
```graphql
|
||||
{
|
||||
shares {
|
||||
name
|
||||
comment
|
||||
}
|
||||
}
|
||||
unraid(action="disk", subaction="log_files") # List available logs
|
||||
unraid(action="disk", subaction="logs", path="syslog", lines=50) # Read syslog
|
||||
unraid(action="disk", subaction="logs", path="/var/log/syslog") # Full path also works
|
||||
```
|
||||
|
||||
### Docker Containers
|
||||
```graphql
|
||||
{
|
||||
docker {
|
||||
containers {
|
||||
id
|
||||
names
|
||||
image
|
||||
state
|
||||
status
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
unraid(action="docker", subaction="list")
|
||||
unraid(action="docker", subaction="details", container_id="plex")
|
||||
unraid(action="docker", subaction="start", container_id="nginx")
|
||||
unraid(action="docker", subaction="stop", container_id="nginx")
|
||||
unraid(action="docker", subaction="restart", container_id="sonarr")
|
||||
unraid(action="docker", subaction="networks")
|
||||
```
|
||||
|
||||
### Virtual Machines
|
||||
```graphql
|
||||
{
|
||||
vms {
|
||||
id
|
||||
name
|
||||
state
|
||||
cpus
|
||||
memory
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### List Log Files
|
||||
```graphql
|
||||
{
|
||||
logFiles {
|
||||
name
|
||||
size
|
||||
modifiedAt
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Read Log Content
|
||||
```graphql
|
||||
{
|
||||
logFile(path: "syslog", lines: 20) {
|
||||
content
|
||||
totalLines
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### System Info
|
||||
```graphql
|
||||
{
|
||||
info {
|
||||
time
|
||||
cpu { model cores threads }
|
||||
os { distro release }
|
||||
system { manufacturer model }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### UPS Devices
|
||||
```graphql
|
||||
{
|
||||
upsDevices {
|
||||
id
|
||||
name
|
||||
status
|
||||
charge
|
||||
load
|
||||
}
|
||||
}
|
||||
unraid(action="vm", subaction="list")
|
||||
unraid(action="vm", subaction="details", vm_id="<id>")
|
||||
unraid(action="vm", subaction="start", vm_id="<id>")
|
||||
unraid(action="vm", subaction="stop", vm_id="<id>")
|
||||
unraid(action="vm", subaction="reboot", vm_id="<id>")
|
||||
unraid(action="vm", subaction="force_stop", vm_id="<id>", confirm=True) # ⚠️
|
||||
```
|
||||
|
||||
### Notifications
|
||||
|
||||
**Counts:**
|
||||
```graphql
|
||||
{
|
||||
notifications {
|
||||
overview {
|
||||
unread { info warning alert total }
|
||||
archive { info warning alert total }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
unraid(action="notification", subaction="overview")
|
||||
unraid(action="notification", subaction="unread")
|
||||
unraid(action="notification", subaction="list", filter="UNREAD", limit=10)
|
||||
unraid(action="notification", subaction="archive", notification_id="<id>")
|
||||
unraid(action="notification", subaction="create", title="Test", subject="Subject",
|
||||
description="Body", importance="normal")
|
||||
```
|
||||
|
||||
**List Unread:**
|
||||
```graphql
|
||||
{
|
||||
notifications {
|
||||
list(filter: { type: UNREAD, offset: 0, limit: 10 }) {
|
||||
id
|
||||
subject
|
||||
description
|
||||
timestamp
|
||||
}
|
||||
}
|
||||
}
|
||||
### API Keys
|
||||
```
|
||||
unraid(action="key", subaction="list")
|
||||
unraid(action="key", subaction="create", name="my-key", roles=["viewer"])
|
||||
unraid(action="key", subaction="delete", key_id="<id>", confirm=True) # ⚠️
|
||||
```
|
||||
|
||||
**List Archived:**
|
||||
```graphql
|
||||
{
|
||||
notifications {
|
||||
list(filter: { type: ARCHIVE, offset: 0, limit: 10 }) {
|
||||
id
|
||||
subject
|
||||
description
|
||||
timestamp
|
||||
}
|
||||
}
|
||||
}
|
||||
### Plugins
|
||||
```
|
||||
unraid(action="plugin", subaction="list")
|
||||
unraid(action="plugin", subaction="add", names=["community.applications"])
|
||||
unraid(action="plugin", subaction="remove", names=["old.plugin"], confirm=True) # ⚠️
|
||||
```
|
||||
|
||||
## Field Name Notes
|
||||
|
||||
- Use `metrics` for real-time usage (CPU/memory percentages)
|
||||
- Use `info` for hardware specs (cores, model, etc.)
|
||||
- Temperature field is `temp` (not `temperature`)
|
||||
- Status field is `state` for array (not `status`)
|
||||
- Sizes are in kilobytes
|
||||
- Temperatures are in Celsius
|
||||
|
||||
## Response Structure
|
||||
|
||||
All responses follow this pattern:
|
||||
```json
|
||||
{
|
||||
"data": {
|
||||
"queryName": { ... }
|
||||
}
|
||||
}
|
||||
### rclone
|
||||
```
|
||||
unraid(action="rclone", subaction="list_remotes")
|
||||
unraid(action="rclone", subaction="delete_remote", name="<remote>", confirm=True) # ⚠️
|
||||
```
|
||||
|
||||
Errors appear in:
|
||||
```json
|
||||
{
|
||||
"errors": [
|
||||
{ "message": "..." }
|
||||
]
|
||||
}
|
||||
### Live Subscriptions (real-time)
|
||||
```
|
||||
unraid(action="live", subaction="cpu")
|
||||
unraid(action="live", subaction="memory")
|
||||
unraid(action="live", subaction="parity_progress")
|
||||
unraid(action="live", subaction="log_tail")
|
||||
unraid(action="live", subaction="notification_feed")
|
||||
unraid(action="live", subaction="ups_status")
|
||||
```
|
||||
> Returns `{"status": "connecting"}` on first call — retry momentarily.
|
||||
|
||||
---
|
||||
|
||||
## Domain → action= Mapping
|
||||
|
||||
| Old tool name (pre-v1.0) | New `action=` |
|
||||
|--------------------------|---------------|
|
||||
| `unraid_info` | `system` |
|
||||
| `unraid_health` | `health` |
|
||||
| `unraid_array` | `array` |
|
||||
| `unraid_storage` | `disk` |
|
||||
| `unraid_docker` | `docker` |
|
||||
| `unraid_vm` | `vm` |
|
||||
| `unraid_notifications` | `notification` |
|
||||
| `unraid_keys` | `key` |
|
||||
| `unraid_plugins` | `plugin` |
|
||||
| `unraid_rclone` | `rclone` |
|
||||
| `unraid_settings` | `setting` |
|
||||
| `unraid_customization` | `customization` |
|
||||
| `unraid_oidc` | `oidc` |
|
||||
| `unraid_users` | `user` |
|
||||
| `unraid_live` | `live` |
|
||||
|
||||
@@ -1,36 +1,105 @@
|
||||
# Unraid API Troubleshooting Guide
|
||||
# Unraid MCP — Troubleshooting Guide
|
||||
|
||||
Common issues and solutions when working with the Unraid GraphQL API.
|
||||
## Credentials Not Configured
|
||||
|
||||
## "Cannot query field" error
|
||||
**Error:** `CredentialsNotConfiguredError` or message containing `~/.unraid-mcp/.env`
|
||||
|
||||
Field name doesn't exist in your Unraid version. Use introspection to find valid fields:
|
||||
|
||||
```bash
|
||||
./scripts/unraid-query.sh -q "{ __type(name: \"TypeName\") { fields { name } } }"
|
||||
**Fix:** Run setup to configure credentials interactively:
|
||||
```
|
||||
unraid(action="health", subaction="setup")
|
||||
```
|
||||
|
||||
## "API key validation failed"
|
||||
- Check API key is correct and not truncated
|
||||
- Verify key has appropriate permissions (use "Viewer" role)
|
||||
- Ensure URL includes `/graphql` endpoint (e.g. `http://host/graphql`)
|
||||
This writes `UNRAID_API_URL` and `UNRAID_API_KEY` to `~/.unraid-mcp/.env`. Re-run at any time to update or rotate credentials.
|
||||
|
||||
## Empty results
|
||||
Many queries return empty arrays when no data exists:
|
||||
- `docker.containers` - No containers running
|
||||
- `vms` - No VMs configured (or VM service disabled)
|
||||
- `notifications` - No active alerts
|
||||
- `plugins` - No plugins installed
|
||||
---
|
||||
|
||||
This is normal behavior, not an error. Ensure your scripts handle empty arrays gracefully.
|
||||
## Connection Failed / API Unreachable
|
||||
|
||||
## "VMs are not available" (GraphQL Error)
|
||||
If the VM manager is disabled in Unraid settings, querying `{ vms { ... } }` will return a GraphQL error.
|
||||
**Solution:** Check if VM service is enabled before querying, or use error handling (like `IGNORE_ERRORS=true` in dashboard scripts) to process partial data.
|
||||
**Symptoms:** Timeout, connection refused, network error
|
||||
|
||||
## URL connection issues
|
||||
- Use HTTPS (not HTTP) for remote access if configured
|
||||
- For local access: `http://unraid-server-ip/graphql`
|
||||
- For Unraid Connect: Use provided URL with token in hostname
|
||||
- Use `-k` (insecure) with curl if using self-signed certs on local HTTPS
|
||||
- Use `-L` (follow redirects) if Unraid redirects HTTP to HTTPS
|
||||
**Diagnostic steps:**
|
||||
|
||||
1. Test basic connectivity:
|
||||
```
|
||||
unraid(action="health", subaction="test_connection")
|
||||
```
|
||||
|
||||
2. Full diagnostic report:
|
||||
```
|
||||
unraid(action="health", subaction="diagnose")
|
||||
```
|
||||
|
||||
3. Check that `UNRAID_API_URL` in `~/.unraid-mcp/.env` points to the correct Unraid GraphQL endpoint.
|
||||
|
||||
4. 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.
|
||||
|
||||
Reference in New Issue
Block a user