AI导哈

Unraid服务器管理协议

一个为AI助手提供控制访问的MCP服务器，用于管理Unraid服务器上的Docker容器、虚拟机和系统健康状态。

  • by JamesPrial
  • Go
  • 本地部署
  • 更新于
在 GitHub 查看 JamesPrial/unraid-mcp

使用说明

unraid mcp

一个MCP（模型上下文协议）服务器，为AI助手提供受控访问权限，以管理Unraid服务器上的Docker容器、虚拟机和系统健康状况。

在Unraid上作为Docker容器运行。通过带有承载令牌身份验证的流式HTTP连接到Claude Code（或任何MCP客户端）。

特性

跨三个领域的31个MCP工具：

  • Docker（16个工具） --列出、检查、启动、停止、重新启动、删除、创建容器；拉取图像；查看日志和统计数据；列出、检查、创建、删除、连接、断开网络连接
  • 虚拟机（12个工具） --列出、检查、启动、停止、强制停止、暂停、恢复、重启、创建、删除虚拟机；列出并创建快照（通过libvirt）
  • 系统健康（3个工具） --CPU/内存/温度概述、Unraid阵列状态、每个磁盘信息

安全护栏：

  • 认证 --所有请求都需要承载令牌
  • 确认提示 --破坏性操作（停止、删除、删除）需要使用一次性、有时间限制的令牌进行两步确认流程
  • 允许名单/拒绝名单 --对容器和VM名称进行glob模式过滤；服务器自己的容器始终受到保护
  • 审核日志记录 --每个工具调用都以换行符分隔的JSON形式记录，并带有时间戳、参数、结果和持续时间

快速开始

1.在Unraid上部署

git clone https://github.com/jamesprial/unraid-mcp.git
cd unraid-mcp

# Set your auth token (or leave empty to auto-generate one)
export UNRAID_MCP_AUTH_TOKEN="your-secret-token"

# Build and run
docker compose up -d

服务器在端口8080上启动。如果没有设置身份验证令牌，则会生成一个并打印到容器日志中：

docker logs unraid-mcp

2.配置克劳德代码

添加到您的 .mcp.json:

{
  "mcpServers": {
    "unraid": {
      "type": "streamable-http",
      "url": "http://<unraid-ip>:8080/mcp",
      "headers": {
        "Authorization": "Bearer your-secret-token"
      }
    }
  }
}

3.使用它

让Claude管理您的Unraid服务器：

  • “列出所有正在运行的Docker容器”
  • “停止plex容器”
  • “阵列状态如何？”
  • “显示磁盘温度”
  • “启动Windows 10虚拟机”

配置

复制并编辑示例配置：

cp config.example.yaml config/config.yaml

server:
  port: 8080
  auth_token: ""          # set here or via UNRAID_MCP_AUTH_TOKEN env var

safety:
  docker:
    allowlist: []          # empty = all containers allowed
    denylist:
      - "unraid-mcp"      # prevent self-management
      - "*backup*"         # glob patterns supported
  vms:
    allowlist: []
    denylist: []

paths:
  emhttp: "/host/emhttp"
  proc: "/host/proc"
  sys: "/host/sys"
  docker_socket: "/var/run/docker.sock"
  libvirt_socket: "/var/run/libvirt/libvirt-sock"

audit:
  enabled: true
  log_path: "/config/audit.log"
  max_size_mb: 50

环境变量

变量 描述
UNRAID_MCP_AUTH_TOKEN 承载令牌（覆盖配置文件）
UNRAID_MCP_CONFIG_PATH 配置文件路径（默认： /config/config.yaml)

集装箱支架

主机路径 容器路径 模式 用途
/var/run/docker.sock /var/run/docker.sock rw Docker API
/var/run/libvirt/libvirt-sock /var/run/libvirt/libvirt-sock rw 通过libvirt管理虚拟机
/var/local/emhttp /host/emhttp ro 取消阵列和磁盘状态
/proc /host/proc ro CPU和内存统计信息
/sys /host/sys ro 硬件温度
./config /config rw 配置文件和审核日志

安全模型

确认流程

破坏性工具(docker_stop, docker_remove, vm_delete等等）使用两步确认：

  1. 第一个调用返回操作的描述和 confirmation_token
  2. 使用令牌的第二次调用执行操作
  3. 代币为一次性使用，5分钟后过期

允许名单/拒绝名单

使用glob模式按名称过滤容器和VM。Denylist总是优先考虑。MCP服务器自己的容器(unraid-mcp)总是被含蓄地否认。

审核日志

所有操作都记录到 /config/audit.log 作为换行符分隔的JSON：

{"timestamp":"2025-01-15T10:30:00Z","tool":"docker_stop","params":{"id":"plex"},"result":"ok","duration_ns":150000000}

发展

# Run tests
go test ./...

# Run with race detector
go test -race ./...

# Build without libvirt (VM tools return stub errors)
go build ./...

# Build with libvirt support
go build -tags libvirt ./...

许可证

麻省理工学院

相关 MCP