Token导航 LogoToken导航TokenDH.com
Unraid MCP Server logo
运维云端stdio官方来源来源级核验

Unraid MCP Server

MCP Server

GraphQL支持的Unraid管理控制协议服务器,提供系统检查、管理操作、实时遥测和需要明确确认的破坏性操作。

工具数

4

提示词数

0

GitHub Stars

65

资源数

0
系统监控PythonClaudeClaude

安装说明

本站只整理中文说明和来源信息,不托管安装包,也不代用户安装。

作者 / 组织

jmagar

提供方

jmagar

最后核验

2026/5/17 20:24

运行时

Python

快速接入

先看主来源和安装命令,再打开仓库或文档;下面只保留这个条目的关键接入事实。

命令预览

uv run unraid-mcp-server

详细介绍

解除MCP的突袭

用于Unraid的GraphQL支持的MCP服务器。暴露统一 unraid 用于系统检查、管理操作、实时遥测和明确确认的破坏性行动的工具。

概述

服务器通过HTTP和WebSocket将MCP工具调用转换为Unraid GraphQL查询和突变。所有操作共享一个 unraid 工具路由 action + subaction实时遥测使用从Unraid API流式传输实时数据的WebSocket订阅。

此存储库提供什么

  • unraid_mcp/ --服务器、GraphQL客户端、WebSocket订阅、配置和工具处理程序
  • skills/unraid/ --面向客户的技能文档
  • docs/ --身份验证、破坏性操作和发布引用
  • .claude-plugin/, .codex-plugin/, gemini-extension.json --客户清单
  • docker-compose.yaml, Dockerfile, entrypoint.sh --集装箱部署
  • tests/ --单元、安全、模式、HTTP层和实时覆盖

工具

工具索引

工具目的
unraid用于所有操作的统一动作/子动作路由器
unraid_help将此引用作为Markdown返回
diagnose_subscriptionsWebSocket订阅系统的完整诊断转储
test_subscription_query探测原始GraphQL订阅以进行模式/调试工作

unraid --行动小组

所有操作都通过一个工具进行。选择一个 action,然后a subaction 在里面。

system --18个子动作

服务器信息、指标、网络和UPS。

子节描述必填参数
overview操作系统、CPU、内存布局、版本、机器ID--
array阵列状态、容量、磁盘运行状况摘要--
network访问URL、HTTP/HTTPS端口、LAN/WAN IP--
registration许可证类型、密钥文件、过期--
variables完整的Unraid变量集(时区、共享等)--
metrics实时CPU百分比和内存使用率--
services正在运行具有名称、联机状态、版本--的服务
display当前UI主题名称--
config配置有效性和错误状态--
online布尔可达性检查--
owner所有者用户名、头像、个人资料URL--
settings统一设置键/值映射--
server单次调用摘要:主机名、正常运行时间、Unraid版本、阵列状态--
servers所有具有LAN/WAN IP和URL的注册服务器--
flash闪存驱动器供应商和产品信息--
ups_devices所有带有电池和功率指标的UPS设备--
ups_device单个UPS设备详细信息device_id
ups_configUPS守护程序配置--

health --4个子动作

连接和系统健康诊断。

子节描述必填参数
check全面健康:API延迟、数组状态、警报、Docker容器摘要-
test_connectionPing Unraid API并返回以ms为单位的延迟-
diagnose订阅系统状态、错误计数、重新连接状态--
setup交互式凭证设置(支持MCP启发)--

array --13个子行动

奇偶校验和阵列磁盘操作。标有\*的破坏性子行为。

子节描述必需参数破坏性
parity_status当前奇偶校验进度、速度、错误----
parity_history过去的奇偶校验结果----
parity_start开始奇偶校验correct (bool)
parity_pause暂停正在运行的奇偶校验----
parity_resume恢复暂停的奇偶校验----
parity_cancel取消正在运行的奇偶校验----
start_array启动Unraid数组----
stop_array停止Unraid阵列confirm=True*
add_disk向阵列中添加磁盘disk_id;可选 slot
remove_disk从阵列中删除磁盘(必须停止阵列)disk_id, confirm=True*
mount_disk装载阵列磁盘disk_id
unmount_disk卸载阵列磁盘disk_id
clear_disk_stats清除磁盘的I/O统计信息(不可逆)disk_id, confirm=True*

disk --6个子动作

共享、物理磁盘、日志文件和闪存备份。标有\*的破坏性子行为。

子节描述必需参数破坏性
shares所有用户共享,包括大小、分配设置、LUKS状态----
disks物理磁盘列表(ID、设备、名称)----
disk_details单盘:序列号、大小、温度disk_id
log_files列出可用日志文件(名称、路径、大小、已修改)----
logs读取具有行范围的日志文件内容log_path;可选 tail_lines (默认值为100,最大值为10000)--
flash_backup启动闪存驱动器到远程的rclone备份remote_name, source_path (必须以 /boot), destination_path, confirm=True*

flash_backup 细节: 呼叫Unraid initiateFlashBackup GraphQL突变,触发rclone从闪存驱动器复制到配置的rclone远程。如果远程上的目标存在,则会被覆盖。退货 { status, jobId }。要还原:使用rclone将备份复制回闪存驱动器,或提取单个配置文件。首先通过配置rclone遥控器 rclone/create_remote.

docker --7个子行动

容器生命周期和网络检查。没有破坏性的子动作。

子节描述必填参数
list所有容器:ID、名称、图像、状态、状态、autoStart--
details完整容器详细信息:端口、装载、标签、网络设置container_id
start启动容器container_id
stop停止容器container_id
restart停止然后启动容器(按顺序停止+启动)container_id
networks所有Docker网络:ID、名称、驱动程序、作用域--
network_details具有IPv6、容器、选项、标签的单一网络network_id

容器标识符接受完整ID、短ID前缀、确切名称或明确的名称前缀。突变(start, stop, restart)需要确切的姓名或完整的ID。

vm --9个子行动

虚拟机生命周期。标有\*的破坏性子行为。

子节描述必需参数破坏性
list所有虚拟机:ID、名称、状态、UUID----
details单个VM详细信息vm_id
start启动虚拟机vm_id
stop优雅地停止虚拟机vm_id
pause暂停正在运行的虚拟机vm_id
resume恢复已暂停的虚拟机vm_id
reboot重新启动虚拟机vm_id
force_stop虚拟机硬断电(可能丢失数据)vm_id, confirm=True*
reset在没有正常关机的情况下硬重置虚拟机vm_id, confirm=True*

vm_id 接受UUID、前缀ID或VM名称。

notification --12个子动作

系统通知CRUD。标有\*的破坏性子行为。

子节描述必需参数破坏性
overview按重要性(信息/警告/警报)列出的未读和存档计数----
list分页通知列表list_type (未预付或存档,默认为未预付);可选的 importance, offset, limit
create创建通知title (≤200), subject (≤500), description (≤2000), importance (信息/警告/警报)--
archive存档单个通知notification_id
mark_unread将已存档的通知移回未读状态notification_id
recalculate重新计算概览计数----
archive_all存档所有未读通知可选 importance 筛选--
archive_many按ID存档特定通知notification_ids (列表)--
unarchive_many按ID对特定通知进行无存档notification_ids (列表)--
unarchive_all将所有已存档的通知移回未读状态可选 importance 筛选--
delete永久删除单个通知notification_id, notification_type, confirm=True*
delete_archived永久删除所有存档的通知confirm=True*

key --7个子行动

API密钥管理。标有\*的破坏性子行为。

子节描述必需参数破坏性
list具有角色和权限的所有API密钥--
get单个API关键详细信息key_id
create创建API密钥name;可选 roles, permissions
update更新名称、角色或权限key_id;可选 name, roles, permissions
delete删除API密钥(立即撤销访问)key_id, confirm=True*
add_role向现有密钥添加角色key_id, roles (使用的第一个元素)--
remove_role从现有密钥中删除角色key_id, roles (使用的第一个元素)--

plugin --3个子动作

取消插件管理。标有\*的破坏性子行为。

子节描述必需参数破坏性
list所有已安装的带有版本和模块标志的插件----
add按名称安装插件names (列表);可选的 bundled, restart
remove按名称卸载插件(不重新安装不可逆)names (列表), confirm=True*

rclone --4个子动作

云存储远程管理。标有\*的破坏性子行为。

子节描述必需参数破坏性
list_remotes所有已配置的rclone遥控器,其类型和参数为----
config_form提供程序类型的配置表单架构可选 provider_type
create_remote创建新的rclone遥控器name, provider_type, config_data (字符串/数字/布尔的字典;最多50个键)--
delete_remote删除rclone远程配置(不删除远程数据)name, confirm=True*

setting --2个子动作

系统设置。标有\*的破坏性子行为。

子节描述必需参数破坏性
update更新系统设置(JSON键/值输入)settings_input (dict;最多100个键,仅标量值)--
configure_ups覆盖UPS监控配置ups_config 字典 confirm=True*

customization --5个子动作

UI主题和SSO状态。

子节描述必填参数
theme完整主题、合作伙伴信息和激活码--
public_theme面向公众的主题和合作伙伴信息(未经身份验证的视图)--
is_initial_setup初始安装向导是否已完成--
sso_enabled是否启用SSO--
set_theme设置活动UI主题theme_name

oidc --5个子动作

OpenID连接/SSO提供者管理。

子节描述必填参数
providers所有具有客户端ID、作用域和身份验证规则的OIDC提供程序--
provider单一提供商详细信息provider_id
configuration具有默认允许来源的OIDC配置--
public_providers公共提供者列表(按钮文本、图标、样式)--
validate_session验证OIDC会话令牌token

user --1个子行动

子节描述必填参数
me经过身份验证的用户:ID、名称、描述、角色--

live --11个子操作(WebSocket订阅)

live 操作组从Unraid GraphQL API的活动WebSocket订阅中读取。它不会发出HTTP查询,而是打开一个 graphql-transport-ws 连接,然后等待一个快照或通过窗口收集事件。

两种交付模式:

  • 快照 (SNAPSHOT_ACTIONS):打开订阅并返回在内收到的第一条消息 timeout 秒。对于事件驱动的子操作(parity_progress, ups_status, notifications_overview, owner, server_status),超时意味着最近没有状态更改,而不是错误。
  • 收集 (COLLECT_ACTIONS):打开订阅并累积的所有事件 collect_for 秒,然后返回完整的事件列表。用于流式传输数据,如日志行和通知提要。
子节模式描述必填参数
cpu快照CPU利用率:总百分比和每个内核的细分--
memory快照内存:总内存、已用内存、可用内存、交换内存、百分比--
cpu_telemetry快照CPU功耗和温度--
array_state快照阵列状态、容量、奇偶校验状态--
parity_progress快照(事件驱动)奇偶校验进度、速度、错误--
ups_status快照(事件驱动)UPS电池、充电、运行时间、电源负载--
notifications_overview快照(事件驱动)按重要性列出的通知计数--
owner快照(事件驱动)所有者配置文件更改--
server_status快照(事件驱动)服务器注册和连接--
log_tail收集流式传输日志文件行path (必须以 /var/log//boot/logs/)
notification_feed收集流式传输传入通知--

可选参数 live:

  • collect_for (浮动,默认 5.0)--收集模式子操作的收集窗口(秒)
  • timeout (浮动,默认 10.0)--WebSocket接收超时(秒)

diagnose_subscriptions

返回订阅系统的完整诊断转储:自动启动状态、重新连接配置、每个订阅状态(活动、上次错误、收到的数据)、错误计数和故障排除建议。有用的时候 live 子操作不返回任何数据。

test_subscription_query

接受原始GraphQL订阅字符串并直接通过WebSocket发送。首先验证查询--必须是 subscription 针对白名单字段之一的操作: logFile, containerStats, cpu, memory, array, network, docker, vm.拒绝突变和查询关键字。返回收到的第一条消息或订阅正在等待事件的说明。

破坏性行动总结

所有破坏性行动都需要 confirm=True.省略或忽略 confirm=False 提高a ToolError 在发出任何网络请求之前。

行动子部分注释
arraystop_array取消股份;首先停止容器和虚拟机
arrayremove_disk必须先停止数组
arrayclear_disk_statsI/O统计数据将被永久擦除
vmforce_stop硬断电;未保存的数据可能会丢失
vmreset硬复位;未保存的数据可能会丢失
notificationdelete永久性;需要 notification_type
notificationdelete_archived清除所有存档的通知
rclonedelete_remote仅删除配置;不删除远程数据
keydelete立即撤销使用该密钥的所有客户端
diskflash_backup覆盖目的地;配置专用遥控器
settingconfigure_ups覆盖UPS守护进程配置
pluginremove不可逆,无需重新安装

刀具参数参考

参数类型由使用
actionstr全部
subactionstr全部
confirmbool(默认值 False)破坏性子动作
device_idstrsystem/ups_device
disk_idstrarray, disk
correct bool的。 array/parity_start
slotintarray/add_disk
log_pathstrdisk/logs
tail_linesint(默认值100,最大值10000)disk/logs
remote_namestrdisk/flash_backup
source_pathstrdisk/flash_backup
destination_pathstrdisk/flash_backup
backup_options 字典 disk/flash_backup
container_idstrdocker 突变和 details
network_idstrdocker/network_details
vm_idstrvm (除 list)
notification_idstrnotification/archive, mark_unread, delete
notification_ids列表notification/archive_many, unarchive_many
notification_typestr(未读/存档)notification/delete
importancestr(信息/警告/警报)notification 过滤并创建
list_typestr(未读/存档,默认为未读)notification/list
titlestr(≤200)notification/create
subjectstr(≤500)notification/create
descriptionstr(≤2000)notification/create
offsetint(默认值0)notification/list
limitint(默认值20)notification/list
key_idstrkey 子行动
namestrkey/create, key/update, rclone
roles列表key 子行动
permissions列表key 子行动
names列表plugin/add, plugin/remove
bundledbool(默认值 False)plugin/add, plugin/remove
restartbool(默认值 True)plugin/add, plugin/remove
provider_typestrrclone/config_form, rclone/create_remote
config_data 字典 rclone/create_remote
settings_input 字典 setting/update
ups_config 字典 setting/configure_ups
theme_namestrcustomization/set_theme
provider_idstroidc/provider
tokenstroidc/validate_session
pathstrlive/log_tail
collect_forfloat(默认值 5.0)live 收集模式子操作
timeoutfloat(默认值 10.0)live 所有子动作

安装

市场

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

本地开发

uv sync --dev
uv run unraid-mcp-server

等效入口点:

uv run unraid-mcp
uv run python -m unraid_mcp

码头工人

docker compose up -d

配置

创建 .env.env.example:

just setup

环境变量

变量必填默认描述
UNRAID_API_URL--GraphQL端点URL,例如。 https://tower.local/graphql
UNRAID_API_KEY-取消获取API密钥(见下文)
UNRAID_MCP_TRANSPORT没有streamable-http运输: streamable-http, stdio,或 sse (已弃用)
UNRAID_MCP_HOST没有0.0.0.0HTTP传输的绑定地址
UNRAID_MCP_PORT没有6970HTTP传输的侦听端口
UNRAID_MCP_BEARER_TOKEN条件--HTTP传输的静态承载令牌;如果未设置,则在首次启动时自动生成
UNRAID_MCP_DISABLE_HTTP_AUTH没有false设置 true 跳过承载身份验证(在处理身份验证的反向代理后面使用)
DOCKER_NETWORK没有--要加入的外部Docker网络;默认网桥留空
PGID没有1000容器工艺GID
PUID没有1000容器进程UID

如何查找UNRAID_API_KEY

  1. 打开Unraid web UI。
  2. 首选 设置→ 管理访问→ API密钥.
  3. 创建新密钥或复制现有密钥。
  4. 将值粘贴到 UNRAID_API_KEY.

UNRAID_API_KEY与UNRAID_MCP_BEARR_TOKEN

这是两个具有不同用途的独立凭据:

  • UNRAID_API_KEY --对MCP服务器进行身份验证 取消GraphQL API每个GraphQL请求都将此键作为头携带。从Unraid web UI获取。
  • UNRAID_MCP_BEARER_TOKEN --身份验证 MCP客户端 (克劳德代码、克劳德桌面等) 此MCP服务器。客户端必须发送 Authorization: Bearer 在每个HTTP请求上。生成方式 openssl rand -hex 32just gen-token.

UNRAID_MCP_DISABLE_HTTP_AUTH

将其设置为 true 当反向代理(nginx、Caddy、Traefik、SWAG)在请求到达MCP服务器之前已经处理了身份验证时。禁用内置检查会删除MCP层的承载令牌要求。启用此标志后,不要将服务器直接暴露在不受信任的网络中。

运输方式

  • streamable-http --违约;公开HTTP端点,除非禁用身份验证,否则需要Bearer令牌
  • stdio --Claude Code本地插件的子进程模式;不需要Bearer令牌
  • sse --旧服务器发送事件;已弃用但功能正常

凭据文件按优先级顺序加载: ~/.unraid-mcp/.env 首先,然后是项目 .env 作为一种退路。

用法示例

系统检查

unraid(action="system", subaction="overview")
unraid(action="system", subaction="array")
unraid(action="live", subaction="cpu")
unraid(action="live", subaction="memory")
unraid(action="health", subaction="check")

奇偶校验工作流程

unraid(action="array", subaction="parity_status")
unraid(action="array", subaction="parity_start", correct=True)   # correcting pass
unraid(action="array", subaction="parity_start", correct=False)  # read-only pass
unraid(action="live",  subaction="parity_progress", timeout=15.0)
unraid(action="array", subaction="parity_pause")
unraid(action="array", subaction="parity_resume")
unraid(action="array", subaction="parity_cancel")
unraid(action="array", subaction="parity_history")

Docker管理

unraid(action="docker", subaction="list")
unraid(action="docker", subaction="start",   container_id="plex")
unraid(action="docker", subaction="stop",    container_id="plex")
unraid(action="docker", subaction="restart", container_id="plex")
unraid(action="docker", subaction="details", container_id="plex")
unraid(action="docker", subaction="networks")

VM操作

unraid(action="vm", subaction="list")
unraid(action="vm", subaction="start",      vm_id="windows11")
unraid(action="vm", subaction="stop",       vm_id="windows11")
unraid(action="vm", subaction="pause",      vm_id="windows11")
unraid(action="vm", subaction="resume",     vm_id="windows11")
unraid(action="vm", subaction="force_stop", vm_id="windows11", confirm=True)

原木拖尾

unraid(action="live", subaction="log_tail",  path="/var/log/syslog", collect_for=5.0)
unraid(action="disk", subaction="logs",      log_path="/var/log/syslog", tail_lines=200)
unraid(action="disk", subaction="log_files")

通知

unraid(action="notification", subaction="overview")
unraid(action="notification", subaction="list", list_type="UNREAD", limit=10)
unraid(action="notification", subaction="list", list_type="UNREAD", importance="ALERT")
unraid(
    action="notification",
    subaction="create",
    title="Test",
    subject="Test notification",
    description="Created via MCP",
    importance="INFO",
)
unraid(action="live", subaction="notification_feed", collect_for=10.0)

闪备

unraid(action="rclone", subaction="list_remotes")
unraid(
    action="disk",
    subaction="flash_backup",
    remote_name="my-backup-remote",
    source_path="/boot",
    destination_path="/flash-backups/tower",
    confirm=True,  # overwrites destination
)

开发命令

命令效果
just dev通过启动开发服务器 uv run python -m unraid_mcp
just test运行完整的测试套件
just lint运行褶边过梁
just fmt运行ruff格式化程序
just typecheck运行pyright或mypy
just test-live运行实时集成测试(需要正在运行的Unraid服务器)
just up从Docker Compose开始
just down停止Docker编写容器
just logs尾部Docker编写容器日志
just health检查 /health 端点
just gen-token生成安全的随机承载令牌
just check-contractDocker安全、烘焙环境和忽略文件检查
just setup创建 .env.env.example 如果丢失
just clean删除构建工件和缓存

验证

just lint
just typecheck
just test

对于stdio MCP烟雾测试:

uv run unraid-mcp-server

之后进行HTTP健康检查 just up:

just health

自动化安全测试 tests/safety/ 验证每一个破坏性行为都会引发 ToolError 没有 confirm=True 在这种情况下,没有GraphQL请求到达网络层。

GraphQL模式概述

服务器针对Unraid GraphQL API发出查询和突变。关键查询根:

由使用
infosystem/overview, system/display,健康检查
arraysystem/array, array/*
varssystem/network, system/variables
metricssystem/metrics
servicessystem/services
serverssystem/servers, system/network
registrationsystem/registration
onlinesystem/online, health/test_connection
ownersystem/owner
settingssystem/settings
flashsystem/flash
upsDevices / upsDeviceByIdsystem/ups_devices, system/ups_device
upsConfigurationsystem/ups_config
parityHistoryarray/parity_history
disk / disksdisk/disk_details, disk/disks
sharesdisk/shares
logFiles / logFiledisk/log_files, disk/logs
docker.containers / docker.networksdocker/*
vmsvm/*
notificationsnotification/*
apiKeys / apiKeykey/*
pluginsplugin/list
rclonerclone/*
customizationcustomization/*
oidcProviders / oidcConfigurationoidc/*
meuser/me

订阅使用 graphql-transport-ws 超越WebSocket(回归传统 graphql-ws).WebSocket URL来源于 UNRAID_API_URL 通过交换方案(httpws, httpswss).

相关插件

插件类别描述
家庭实验室核心核心家庭实验室管理的核心代理、命令、技能和设置/健康工作流程。
监督者mcpmedia通过Overseer搜索电影和电视节目、提交请求和监视失败的请求。
unifi-mcp基础设施监控和管理UniFi设备、客户端、防火墙规则和网络健康状况。
获取mcp实用程序通过自托管的Gotify服务器发送和管理推送通知。
swag mcp基础设施创建、编辑和管理SWAG nginx反向代理配置。
突触mcp基础设施跨家庭实验室主机的Docker管理(Flux)和SSH远程操作(Scout)。
神秘的mcp基础设施通过Arcane管理Docker环境、容器、映像、卷、网络和GitOps。
系统日志mcp基础设施通过SQLite FTS5从所有家庭实验室主机接收、索引和搜索系统日志流。
插件实验室开发工具使用代理和规范模板搭建、审查、对齐和部署homelab MCP插件。

许可证

麻省理工学院

目录标签

目录标签

系统监控PythonClaudeUnraid管理本地部署GraphQL接口Docker管理虚拟机管理

支持客户端

Claude

接入字段

传输方式(transport,传输协议)

stdio

鉴权方式(authType,认证方式)

token

运行时(runtime,运行环境)

Python

部署方式(deploymentType,部署类型)

remote-capable

工具数量(toolCount,工具数)

4

资源数量(resourceCount,资源数)

0

提示词数量(promptCount,提示词数)

0

权限和风险

stdiotokenremote-capable

接入前请确认传输方式、认证方式和部署位置,并根据实际工具能力限制访问范围。

安装前确认

不要直接授予不必要的文件、网络或账号权限;先核对安装命令和配置内容。

来源信息

继续浏览同类 MCP