mirror of https://github.com/jmagar/unraid-mcp.git synced 2026-03-26 05:44:25 -07:00

Files

Jacob Magar 183db70d97 fix: address 17 remaining PR review comments

Resolves review threads:
- PRRT_kwDOO6Hdxs50mcYz: oidc/validate_session now documents required `token`
- PRRT_kwDOO6Hdxs50mcY8: setting/update corrected to require `settings_input`
- PRRT_kwDOO6Hdxs50mcZE: rclone/create_remote corrected to `provider_type`+`config_data`
- PRRT_kwDOO6Hdxs50mcZL: disk/logs corrected to `log_path`+`tail_lines`
- PRRT_kwDOO6Hdxs50mcZe: parity_progress added to event-driven subscriptions list
- PRRT_kwDOO6Hdxs50mcZh: log_tail README example now includes required `path`
- PRRT_kwDOO6Hdxs50mcaR: parity_start quick-reference now includes required `correct=False`
- PRRT_kwDOO6Hdxs50mcaq: array_state documented as "may show" not "will always show"
- PRRT_kwDOO6Hdxs50mnR8: key/create roles is optional; add_role/remove_role use `roles` (plural)
- PRRT_kwDOO6Hdxs50mnRd: endpoints.md heading moved before blockquote (MD041)
- PRRT_kwDOO6Hdxs50mnTB: test_resources.py uses _get_resource() helper instead of raw internals
- PRRT_kwDOO6Hdxs50mYkZ: N/A — _build_google_auth removed in prior refactor commit
- PRRT_kwDOO6Hdxs50mnQf: N/A — plugin.json already at 1.1.2, matches pyproject.toml
- PRRT_kwDOO6Hdxs50mnQ7: N/A — blank line already present in CLAUDE.md
- PRRT_kwDOO6Hdxs50mnRD: N/A — fastmcp.http.json removed in prior refactor commit
- PRRT_kwDOO6Hdxs50mnRH: N/A — blank line already present in README.md
- PRRT_kwDOO6Hdxs50mnSW: N/A — test_auth_builder.py removed in prior refactor commit

2026-03-24 22:50:40 -04:00

examples

fix: harden read-logs.sh against GraphQL injection and path traversal

2026-02-15 23:03:13 -05:00

references

fix: address 17 remaining PR review comments

2026-03-24 22:50:40 -04:00

scripts

fix: harden shell scripts with error handling and null guards

2026-02-15 23:01:40 -05:00

README.md

docs: fix markdown lint, broken links, stale counts, and publishing guidance

2026-02-15 23:05:05 -05:00

setup.sh

fix: address 18 CRITICAL+HIGH PR review comments

2026-02-15 16:42:58 -05:00

SKILL.md

fix: address 17 remaining PR review comments

2026-03-24 22:50:40 -04:00

README.md

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

Installation

This skill is part of the Unraid MCP plugin. Install via the Claude Code marketplace:

/plugin marketplace add jmagar/unraid-mcp
/plugin install unraid @unraid-mcp

The plugin includes both the MCP server and this skill at skills/unraid/.

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

Disk/array sizes are in kilobytes; memory values (from info.memory and metrics.memory) are in bytes
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: 0.2.0
API Version: Unraid 7.2 GraphQL
Tested: 2026-01-21
Endpoints: 27 working read-only queries