Unraid MCP Server

Private, safety-first MCP server for Unraid. Runs as a native Unraid plugin (.plg) with WebGUI settings, GraphQL-only delegation, and nobody:nobody daemon isolation.

Quick Install

Option A: Install from GitHub Releases (Recommended)

1. Go to Releases page: https://github.com/hektyc/unraid-agent/releases/latest
2. Download unraid-agent.plg (right-click → "Save Link As", or click the file then download)
3. In Unraid WebUI: Settings > Plugins > Install Plugin > Choose File
4. Select the downloaded .plg file and click Install
5. Unraid downloads the package (unraid-agent.tar) from Releases and installs it

Option B: GitHub Actions Build

1. Push code to the dev branch
2. Go to Actions tab in GitHub
3. Select Build Unraid Agent Plugin workflow
4. Download the unraid-agent-plg and unraid-agent-package artifacts
5. In Unraid WebUI: Settings > Plugins > Install Plugin
6. Upload the .plg file, and manually install the package

Option C: Build Locally

# Requires Go 1.24+
git clone https://github.com/hektyc/unraid-agent.git
cd unraid-agent
git checkout dev
chmod +x build.sh
./build.sh
# → creates: unraid-agent.plg + unraid-agent.tar.gz

Upload the .plg via Unraid WebUI.

Configuration

After install, go to Settings > Unraid Agent:

Setting	Default	Description
Unraid API URL	http://localhost/graphql	GraphQL endpoint
API Key	(empty)	Unraid API key
Transport	stdio	stdio or streamable-http
Bind Host	127.0.0.1	HTTP bind address
Port	6970	HTTP port
Read Only	true	Keep enabled unless needed
Allow Array Actions	false	Array start/stop
Allow Container Actions	false	Container stop/remove
Allow VM Actions	false	VM stop/force-stop
Allow Destructive	false	Shortcut for all destructive
Bearer Token	(empty)	Manual entry for HTTP auth
Verify SSL	true	TLS verification

Safety

• Default is read-only. All write/mutation operations are blocked unless explicitly enabled.
• Per-action toggles in the WebGUI control exactly which operations are allowed.
• Destructive actions show explicit warnings in tool descriptions.
• MCP server runs as nobody:nobody with GraphQL-only access.

Client Integration

Claude Desktop (stdio)

{
  "mcpServers": {
    "unraid": {
      "command": "ssh",
      "args": ["[email protected]", "/usr/local/emhttp/plugins/unraid-agent/bin/unraid-agent"]
    }
  }
}

HTTP (streamable-http)

{
  "mcpServers": {
    "unraid": {
      "url": "http://tower.local:6970/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Files

Path	Purpose
/usr/local/emhttp/plugins/unraid-agent/	Plugin install dir
/boot/config/plugins/unraid-agent/config.cfg	Persistent settings
/boot/config/plugins/unraid-agent/AGENT-SKILLS.md	Agent skills (editable)
/boot/config/plugins/unraid-agent/AGENT-MEMORY.md	Agent memory (editable)
/var/log/unraid-agent.log	Plugin logs
/usr/local/emhttp/plugins/unraid-agent/bin/unraid-agent	Go binary

AGENT-SKILLS.md and AGENT-MEMORY.md

These files live in /boot/config/plugins/unraid-agent/ and can be edited by you or by the AI agent through the MCP tools. They provide:

• AGENT-SKILLS.md — How-to guides for carrying out tasks
• AGENT-MEMORY.md — Rules, constraints, and remembered state

Branching

• dev — active development, CI builds .plg artifacts
• main — stable releases, auto-tagged .plg builds with GitHub Release assets

Security

• nobody:nobody process isolation
• GraphQL-only delegation (no shell execution)
• Default READ_ONLY=true
• Sensitive values redacted in logs
• Manual bearer token entry (never auto-generated)