Variable

Required

Default

Description

UNRAID_API_URL

Yes

—

GraphQL endpoint URL, e.g. https://tower.local/graphql

UNRAID_API_KEY

Yes

—

Unraid API key (see below)

UNRAID_MCP_TRANSPORT

No

streamable-http

Transport: streamable-http, stdio, or sse (deprecated)

UNRAID_MCP_HOST

No

127.0.0.1 bare metal; Docker sets 0.0.0.0

Bind address for HTTP transports

UNRAID_MCP_PORT

No

6970

Listen port for HTTP transports

UNRAID_MCP_MAX_RESPONSE_BYTES

No

40000

Max serialized tool-response size; over-cap responses return a parseable truncation marker

UNRAID_MCP_BEARER_TOKEN

Conditional

—

Static Bearer token for HTTP transports; auto-generated on first start if unset

UNRAID_MCP_DISABLE_HTTP_AUTH

No

false

Set true to skip Bearer auth (use behind a reverse proxy that handles auth)

UNRAID_MCP_TRUST_PROXY

Conditional

false

Required when disabling HTTP auth while binding a non-loopback interface

UNRAID_MCP_GOOGLE_CLIENT_ID

No

—

Google OAuth client ID; setting both client ID and secret replaces Bearer auth for HTTP transports

UNRAID_MCP_GOOGLE_CLIENT_SECRET

No

—

Google OAuth client secret

UNRAID_MCP_GOOGLE_BASE_URL

Conditional

—

Public server base URL, required when Google OAuth is enabled

UNRAID_MCP_GOOGLE_REQUIRED_SCOPES

No

openid + userinfo.email

Comma/space-separated OAuth scopes

UNRAID_MCP_GOOGLE_ALLOWED_EMAILS

Conditional

—

Verified Google emails allowed to use the MCP server

UNRAID_MCP_GOOGLE_ALLOWED_DOMAINS

Conditional

—

Verified Google email domains allowed to use the MCP server

UNRAID_MCP_GOOGLE_ALLOW_ANY_USER

No

false

Explicitly allow any verified Google account; only for private/trusted deployments

UNRAID_MCP_GOOGLE_REDIRECT_PATH

No

/auth/callback

OAuth callback path configured in Google Cloud

UNRAID_MCP_GOOGLE_JWT_SIGNING_KEY

Conditional

—

With the encryption key, enables restart-surviving encrypted token storage

UNRAID_MCP_GOOGLE_ENCRYPTION_KEY

Conditional

—

Fernet key for encrypted OAuth token storage

UNRAID_MCP_GOOGLE_STORAGE_DIR

No

~/.unraid-mcp/oauth-tokens

Directory for persisted encrypted OAuth tokens

UNRAID_VERIFY_SSL

No

true

Upstream Unraid API TLS verification; may also be a CA-bundle path

UNRAID_ALLOW_INSECURE_TLS

Conditional

false

Required second opt-in when UNRAID_VERIFY_SSL=false

UNRAID_MCP_LOG_LEVEL

No

INFO

Log verbosity: DEBUG, INFO, WARNING, ERROR, CRITICAL

UNRAID_MCP_LOG_FILE

No

unraid-mcp.log

Log filename under logs/ or /app/logs/ in Docker

UNRAID_AUTO_START_SUBSCRIPTIONS

No

true

Auto-start live WebSocket subscriptions on boot

UNRAID_MAX_RECONNECT_ATTEMPTS

No

10

Max WebSocket reconnect attempts

UNRAID_AUTOSTART_LOG_PATH

No

auto-detect

Log file path for the log-tail subscription

UNRAID_CREDENTIALS_DIR

No

~/.unraid-mcp

Override credentials directory

DOCKER_NETWORK

No

—

External Docker network to join; leave blank for default bridge

PGID

No

1000

Container process GID

PUID

No

1000

Container process UID

Tool

Purpose

unraid

Unified action/subaction router for all operations (including help and subscriptions diagnostics)

Subaction

Description

Required params

overview

OS, CPU, memory layout, versions, machine ID

—

array

Array state, capacity, disk health summary

—

network

Access URLs, HTTP/HTTPS ports, LAN/WAN IPs

—

registration

License type, key file, expiration

—

variables

Full Unraid variable set (timezone, shares, etc.)

—

metrics

Current CPU % and memory usage

—

network_metrics

Current network throughput metrics from metrics.network

—

services

Running services with name, online status, version

—

display

Current UI theme name

—

display_details

Direct display root metadata: case, theme, temperature display settings, thresholds, locale

—

config

Config validity and error state

—

online

Boolean reachability check

—

owner

Owner username, avatar, profile URL

—

settings

Unified settings key/value map

—

server

Single-call summary: hostname, uptime, Unraid version, array state

—

server_details

Direct server root details with owner and URLs; API key omitted

—

servers

All registered servers with LAN/WAN IPs and URLs

—

network_access_urls

Direct network.accessUrls entries with type, name, IPv4, and IPv6

—

flash

Flash drive vendor and product info

—

ups_devices

All UPS devices with battery and power metrics

—

ups_device

Single UPS device details

device_id

ups_config

UPS daemon configuration

—

server_time

Current server time, time zone, and NTP config

—

timezones

Available IANA time-zone options (capped)

—

network_interfaces

Extended network interface list with IPv4/IPv6 address details

—

Subaction

Description

Required params

check

Comprehensive health: API latency, array state, alerts, Docker container summary

—

test_connection

Ping the Unraid API and return latency in ms

—

diagnose

Subscription system status, error counts, reconnect state

—

setup

Report credential status and print plugin/.env setup instructions

—

Subaction

Description

Required params

Destructive

parity_status

Current parity check progress, speed, errors

—

—

parity_history

Past parity check results

—

—

assignable_disks

Physical disks not yet in the array (pairs with add_disk)

—

—

parity_start

Start a parity check

correct (bool)

—

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 Unraid array

—

—

stop_array

Stop the Unraid array

confirm=True

*

add_disk

Add a disk to the array

disk_id; optional slot

—

remove_disk

Remove a disk from the array (array must be stopped)

disk_id, confirm=True

*

mount_disk

Mount an array disk

disk_id

—

unmount_disk

Unmount an array disk

disk_id

—

clear_disk_stats

Clear I/O statistics for a disk (irreversible)

disk_id, confirm=True

*

Subaction

Description

Required params

Destructive

shares

All user shares with size, allocation settings, LUKS status

—

—

disks

Physical disk list (ID, device, name)

—

—

disk_details

Single disk: serial, size, temperature

disk_id

—

log_files

List available log files (name, path, size, modified)

—

—

logs

Read log file content with line range

log_path; optional tail_lines (default 100, max 10000)

—

flash_backup

Initiate rclone backup of the flash drive to a remote

remote_name, source_path (must start with /boot), destination_path, confirm=True

*

Subaction

Description

Required params

Destructive

list

All containers: ID, names, image, state, status, autoStart

—

—

details

Full container detail: ports, mounts, labels, network settings

container_id

—

logs

Not available via the Unraid GraphQL API — returns guidance to use docker logs on the host

container_id

—

ports

All host port bindings across running containers, sorted by (host_port, protocol).

—

—

start

Start a container

container_id

—

stop

Stop a container

container_id

—

restart

Stop then start a container (stop + start in sequence)

container_id

—

unpause

Unpause a paused container

container_id

—

remove_container

Remove a container (optionally its image via with_image)

container_id, confirm=True

*

update_container

Apply a pending image update to one container

container_id

—

update_containers

Apply image updates to several containers

container_ids

—

update_all_containers

Apply all pending container image updates

—

—

update_autostart

Set container autostart config

autostart_entries ([{id, autoStart, wait?}])

—

refresh_digests

Refresh image digests (recheck for updates)

—

—

sync_template_paths

Sync Docker template paths

—

—

reset_template_mappings

Reset template path mappings to defaults

confirm=True

*

create_folder

Create an organizer folder

organizer_input ({name, …})

—

create_folder_with_items

Create a folder containing items

organizer_input

—

rename_folder

Rename a folder

organizer_input ({folderId, newName})

—

set_folder_children

Set a folder's children

organizer_input ({childrenIds, …})

—

delete_entries

Delete organizer entries

organizer_input ({entryIds}), confirm=True

*

move_entries_to_folder

Move entries into a folder

organizer_input

—

move_items_to_position

Move items to a position

organizer_input

—

update_view_preferences

Update organizer view preferences

organizer_input ({prefs, …})

—

networks

All Docker networks: ID, name, driver, scope

—

—

network_details

Single network with IPv6, containers, options, labels

network_id

—

Subaction

Description

Required params

Destructive

list

All VMs: ID, name, state, UUID

—

—

details

Single VM details

vm_id

—

start

Start a VM

vm_id

—

stop

Gracefully stop a VM

vm_id

—

pause

Pause a running VM

vm_id

—

resume

Resume a paused VM

vm_id

—

reboot

Reboot a VM

vm_id

—

force_stop

Hard power-off a VM (data loss possible)

vm_id, confirm=True

*

reset

Hard reset a VM without graceful shutdown

vm_id, confirm=True

*

Subaction

Description

Required params

Destructive

overview

Unread and archive counts by importance (INFO/WARNING/ALERT)

—

—

list

Paginated notification list

list_type (UNREAD or ARCHIVE, default UNREAD); optional importance, offset, limit

—

create

Create a notification

title (≤200), subject (≤500), description (≤2000), importance (INFO/WARNING/ALERT)

—

notify_if_unique

Create a notification only if an identical one does not already exist

title, subject, description, importance

—

archive

Archive a single notification

notification_id

—

mark_unread

Move an archived notification back to unread

notification_id

—

recalculate

Recalculate the overview counts

—

—

archive_all

Archive all unread notifications

optional importance to filter

—

archive_many

Archive specific notifications by ID

notification_ids (list)

—

unarchive_many

Unarchive specific notifications by ID

notification_ids (list)

—

unarchive_all

Move all archived notifications back to unread

optional importance to filter

—

delete

Permanently delete a single notification

notification_id, notification_type, confirm=True

*

delete_archived

Permanently delete all archived notifications

confirm=True

*

Subaction

Description

Required params

Destructive

list

All API keys with roles and permissions

—

—

get

Single API key details

key_id

—

possible_roles

All assignable roles

—

—

possible_permissions

All grantable resource/action permissions

—

—

permissions_for_roles

Permissions implied by given roles

roles

—

preview_permissions

Effective permissions for roles and/or permissions

roles and/or permissions_input ([{resource, actions}])

—

auth_actions

All available auth actions

—

—

creation_form_schema

JSON-schema form for key creation

—

—

create

Create an API key

name; optional roles, permissions

—

update

Update name, roles, or permissions

key_id; optional name, roles, permissions

—

delete

Delete an API key (immediately revokes access)

key_id, confirm=True

*

add_role

Add a role to an existing key

key_id, roles (first element used)

—

remove_role

Remove a role from an existing key

key_id, roles (first element used)

—

Subaction

Description

Required params

Destructive

list

All installed plugins with version and module flags

—

—

installed_unraid

Raw installed .plg filenames

—

—

install_operations

List async plugin-install operations

—

—

install_operation

Status of one install operation

operation_id

—

add

Install plugins by name

names (list); optional bundled, restart

—

remove

Uninstall plugins by name (irreversible without re-install)

names (list), confirm=True

*

install

Async-install a .plg URL — runs code as root (poll via install_operation)

url, confirm=True; optional plugin_name, forced

*

install_language

Async-install a language pack — runs code as root

url, confirm=True

*

Subaction

Description

Required params

Destructive

list_remotes

All configured rclone remotes with type and parameters

—

—

config_form

Config form schema for a provider type

optional provider_type

—

create_remote

Create a new rclone remote

name, provider_type, config_data (dict of string/number/bool; max 50 keys)

—

delete_remote

Delete a rclone remote config (does not delete remote data)

name, confirm=True

*

Subaction

Description

Required params

Destructive

update

Update system settings (JSON key/value input)

settings_input (dict; max 100 keys, scalar values only)

—

configure_ups

Overwrite UPS monitoring configuration

ups_config (dict), confirm=True

*

update_ssh

Update SSH daemon settings (can cut off shell access)

config_input ({enabled, port}), confirm=True

*

update_temperature

Update temperature sensor configuration

config_input

—

update_system_time

Update timezone / NTP / manual time — can invalidate TLS certs

config_input, confirm=True

*

update_server_identity

Update server name, comment, and model

name; optional comment, sys_model

—

Subaction

Description

Required params

Destructive

remote_access

Current remote-access settings (type, forward, port)

—

—

cloud

Unraid Connect / cloud status (relay, minigraph, key validity)

—

—

status

Direct connect root status: dynamic remote access and settings schema; settings values omitted

—

—

update_api_settings

Update Connect API settings (affects internet reachability)

connect_input ({accessType?, forwardType?, port?}), confirm=True

*

sign_in

Sign the server in to Unraid Connect — registers with the cloud

connect_input ({apiKey, userInfo?}), confirm=True

*

sign_out

Sign the server out of Unraid Connect

confirm=True

*

setup_remote_access

Configure remote access — can expose the server to the internet

connect_input, confirm=True

*

enable_dynamic_remote_access

Toggle dynamic remote access

connect_input ({url, enabled}), confirm=True

*

Subaction

Description

Required params

public_theme

Public-facing theme (also the server's current theme)

—

is_initial_setup

Whether this is a fresh install (isFreshInstall)

—

sso_enabled

Whether SSO is enabled

—

details

Direct customization root onboarding/language details; activation-code values omitted

—

set_theme

Set the active UI theme

theme_name

set_locale

Set the UI locale

locale

Subaction

Description

Required params

providers

All OIDC providers with client ID, scopes, auth rules

—

provider

Single provider details

provider_id

configuration

OIDC configuration with default allowed origins

—

public_providers

Public provider list (button text, icon, style)

—

validate_session

Validate an OIDC session token

token

Subaction

Description

Required params

Destructive

internal_boot_context

Internal boot / first-boot context

—

—

complete

Mark onboarding complete

—

—

open

Open the onboarding flow

—

—

close

Close the onboarding flow

—

—

resume

Resume onboarding

—

—

bypass

Bypass onboarding

—

—

reset

Reset onboarding/setup state

confirm=True

*

set_override

Set an onboarding override

onboarding_input

—

clear_override

Clear the onboarding override

—

—

refresh_internal_boot_context

Recompute the internal boot context

—

—

create_internal_boot_pool

Create an internal boot pool — FORMATS devices, may REBOOT

onboarding_input, confirm=True

*

Subaction

Description

Required params

me

Authenticated user: ID, name, description, roles

—

Subaction

Mode

Description

Required params

cpu

Snapshot

CPU utilization: total % and per-core breakdown

—

memory

Snapshot

Memory: total, used, free, swap, percentages

—

cpu_telemetry

Snapshot

CPU power draw and temperature

—

array_state

Snapshot

Array state, capacity, parity check status

—

parity_progress

Snapshot (event-driven)

Parity check progress, speed, errors

—

ups_status

Snapshot (event-driven)

UPS battery, charge, runtime, power load

—

notifications_overview

Snapshot (event-driven)

Notification counts by importance

—

notifications_warnings

Snapshot (event-driven)

Warnings/alerts feed (filtered)

—

owner

Snapshot (event-driven)

Owner profile changes

—

server_status

Snapshot (event-driven)

Server registration and connectivity

—

display

Snapshot (event-driven)

Theme/display changes

—

docker_container_stats

Snapshot

Per-container CPU/memory/IO stats

—

temperature

Snapshot

Temperature sensor readings

—

network_metrics

Snapshot

Network throughput metrics

—

log_tail

Collect

Stream log file lines

path (must start with /var/log/ or /boot/logs/)

notification_feed

Collect

Stream incoming notifications

—

plugin_install_updates

Collect

Stream plugin-install progress events

operation_id (required)

Subaction

Description

Required params

diagnose

Full diagnostic dump: auto-start status, reconnect config, per-subscription state (active, last error, data received), error counts, and troubleshooting recommendations

—

test_query

Send a raw GraphQL subscription string directly over WebSocket to debug schema/field issues

subscription_query

Action

Subaction

Notes

array

stop_array

Unmounts shares; stop containers and VMs first

array

remove_disk

Array must be stopped first

array

clear_disk_stats

I/O stats are permanently erased

vm

force_stop

Hard power-off; unsaved data may be lost

vm

reset

Hard reset; unsaved data may be lost

notification

delete

Permanent; requires notification_type

notification

delete_archived

Wipes all archived notifications

rclone

delete_remote

Removes config only; does not delete remote data

key

delete

Immediately revokes all clients using that key

disk

flash_backup

Overwrites destination; configure a dedicated remote

setting

configure_ups

Overwrites UPS daemon config

setting

update_ssh

Can cut off remote shell access (disable SSH / change port)

setting

update_system_time

Clock changes can invalidate TLS certs / break time-sensitive services

plugin

remove

Irreversible without re-install

plugin

install / install_language

Fetches and runs a .plg from a URL as root

connect

sign_in

Registers the server with the Unraid Connect cloud

connect

update_api_settings

Changes remote-access posture / internet reachability

docker

remove_container

Removes a container (and optionally its image)

docker

reset_template_mappings

Resets Docker template path mappings to defaults

docker

delete_entries

Deletes Docker organizer entries

connect

sign_out

Signs the server out of Unraid Connect

connect

setup_remote_access

Reconfigures remote access; can expose the server

connect

enable_dynamic_remote_access

Toggles dynamic remote access

onboarding

reset

Resets onboarding/setup state

onboarding

create_internal_boot_pool

Formats devices and may reboot the server

Parameter

Type

Used by

action

str

all

subaction

str

all

confirm

bool (default False)

destructive subactions

device_id

str

system/ups_device

disk_id

str

array, disk

correct

bool

array/parity_start

slot

int

array/add_disk

log_path

str

disk/logs

tail_lines

int (default 100, max 10000)

disk/logs

remote_name

str

disk/flash_backup

source_path

str

disk/flash_backup

destination_path

str

disk/flash_backup

backup_options

dict

disk/flash_backup

container_id

str

docker mutations and details

container_ids

list[str]

docker/update_containers

with_image

bool (default False)

docker/remove_container

autostart_entries

list[dict]

docker/update_autostart

organizer_input

dict

docker organizer subactions

network_id

str

docker/network_details

vm_id

str

vm (all except list)

notification_id

str

notification/archive, mark_unread, delete

notification_ids

list[str]

notification/archive_many, unarchive_many

notification_type

str (UNREAD/ARCHIVE)

notification/delete

importance

str (INFO/WARNING/ALERT)

notification filter and create

list_type

str (UNREAD/ARCHIVE, default UNREAD)

notification/list

title

str (≤200)

notification/create

subject

str (≤500)

notification/create

description

str (≤2000)

notification/create

offset

int (default 0)

notification/list

limit

int (default 20)

notification/list

key_id

str

key subactions

name

str

key/create, key/update, rclone

roles

list[str]

key subactions

permissions

list[str]

key subactions

permissions_input

list[dict]

key/preview_permissions

names

list[str]

plugin/add, plugin/remove

bundled

bool (default False)

plugin/add, plugin/remove

restart

bool (default True)

plugin/add, plugin/remove

url

str

plugin/install, plugin/install_language

plugin_name

str

plugin/install

forced

bool (default False)

plugin/install

operation_id

str

plugin/install_operation

provider_type

str

rclone/config_form, rclone/create_remote

config_data

dict

rclone/create_remote

settings_input

dict

setting/update

ups_config

dict

setting/configure_ups

config_input

dict

setting/update_ssh, update_temperature, update_system_time

comment

str

setting/update_server_identity

sys_model

str

setting/update_server_identity

connect_input

dict

connect mutations

onboarding_input

dict

onboarding/set_override, create_internal_boot_pool

theme_name

str

customization/set_theme

locale

str

customization/set_locale

provider_id

str

oidc/provider

token

str

oidc/validate_session

path

str

live/log_tail

subscription_query

str

subscriptions/test_query

collect_for

float (default 5.0)

live collect-mode subactions

timeout

float (default 10.0)

live all subactions

Command

Effect

just dev

Start development server via uv run python -m unraid_mcp

just test

Run full test suite

just lint

Run ruff linter

just fmt

Run ruff formatter

just typecheck

Run the ty type checker (uv run ty check unraid_mcp/, matches CI)

just test-live

Run live integration tests (requires a running Unraid server)

just up

Start via Docker Compose

just down

Stop Docker Compose containers

just logs

Tail Docker Compose container logs

just health

Check /health endpoint

just gen-token

Generate a secure random Bearer token

just check-contract

Docker security, baked-env, and ignore-file checks

just setup

Create .env from .env.example if missing

just clean

Remove build artifacts and caches

Root

Used by

info

system/overview, system/display, health check

array

system/array, array/*

vars

system/network, system/variables

metrics

system/metrics

services

system/services

display

system/display_details (safe direct root)

servers

system/servers, system/network

network

system/network_access_urls (safe direct root)

server

system/server_details (safe direct root; API key omitted)

registration

system/registration

online

system/online, health/test_connection

owner

system/owner

settings

system/settings

flash

system/flash

upsDevices / upsDeviceById

system/ups_devices, system/ups_device

upsConfiguration

system/ups_config

parityHistory

array/parity_history

disk / disks

disk/disk_details, disk/disks

shares

disk/shares

logFiles / logFile

disk/log_files, disk/logs

docker.containers / docker.networks

docker/*

vms

vm/*

notifications

notification/*

apiKeys / apiKey

key/*

plugins

plugin/list

rclone

rclone/*

connect

connect/status (safe direct root; settings values omitted), connect/*

customization

customization/details (safe direct root; activation-code values omitted), customization/*

oidcProviders / oidcConfiguration

oidc/*

me

user/me

Plugin

Category

Description

homelab-core

core

Core agents, commands, skills, and setup/health workflows for homelab management.

overseerr-mcp

media

Search movies and TV shows, submit requests, and monitor failed requests via Overseerr.

unifi-mcp

infrastructure

Monitor and manage UniFi devices, clients, firewall rules, and network health.

gotify-mcp

utilities

Send and manage push notifications via a self-hosted Gotify server.

swag-mcp

infrastructure

Create, edit, and manage SWAG nginx reverse proxy configurations.

synapse-mcp

infrastructure

Docker management (Flux) and SSH remote operations (Scout) across homelab hosts.

arcane-mcp

infrastructure

Manage Docker environments, containers, images, volumes, networks, and GitOps via Arcane.

syslog-mcp

infrastructure

Receive, index, and search syslog streams from all homelab hosts via SQLite FTS5.

plugin-lab

dev-tools

Scaffold, review, align, and deploy homelab MCP plugins with agents and canonical templates.