星战科技xingzhan.cloud
返回市场
无阵列MCP服务器

无阵列MCP服务器

作者：jmagar18 星标更新：2025-09-29
安装使用来源：spider==github.com

项目介绍

🚀 Unraid MCP 服务器

Python 版本 FastMCP 许可证

一个强大的 MCP（模型上下文协议）服务器，提供了全面的工具来与 Unraid 服务器的 GraphQL API 进行交互。

✨ 功能

  • 🔧 26 个工具：通过 MCP 协议实现完整的 Unraid 管理
  • 🏗️ 模块化架构：干净、可维护且可扩展的代码库
  • ⚡ 高性能：异步/并发操作并优化超时设置
  • 🔄 实时数据：WebSocket 订阅以实现实时日志流
  • 📊 健康监控：全面的系统诊断和状态
  • 🐳 Docker 就绪：支持 Docker Compose 的完整容器化
  • 🔒 安全：正确的 SSL/TLS 配置和 API 密钥管理
  • 📝 丰富的日志：具有轮换和多个级别的结构化日志

📋 目录

🚀 快速开始

先决条件

  • Docker 和 Docker Compose（推荐）
  • 或者 Python 3.10+ 以及 uv 用于开发
  • 启用了 GraphQL API 的 Unraid 服务器

1. 克隆仓库

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

2. 配置环境

cp .env.example .env
# 编辑 .env 文件，填写你的 Unraid API 详情

3. 使用 Docker 部署（推荐）

# 使用 Docker Compose 启动
docker compose up -d

# 查看日志
docker compose logs -f unraid-mcp

或者 3. 开发运行

# 安装依赖
uv sync

# 运行开发服务器
./dev.sh

📦 安装

🐳 Docker 部署（推荐）

最简单的方式是使用 Docker 来运行 Unraid MCP 服务器：

# 克隆仓库
git clone https://github.com/jmagar/unraid-mcp
cd unraid-mcp

# 设置所需的环境变量
export UNRAID_API_URL="http://your-unraid-server/graphql"
export UNRAID_API_KEY="your_api_key_here"

# 使用 Docker Compose 部署
docker compose up -d

# 查看日志
docker compose logs -f unraid-mcp

手动 Docker 构建

# 手动构建和运行
docker build -t unraid-mcp-server .
docker run -d --name unraid-mcp \
  --restart unless-stopped \
  -p 6970:6970 \
  -e UNRAID_API_URL="http://your-unraid-server/graphql" \
  -e UNRAID_API_KEY="your_api_key_here" \
  unraid-mcp-server

🔧 开发安装

为了开发和测试：

# 克隆仓库
git clone https://github.com/jmagar/unraid-mcp
cd unraid-mcp

# 使用 uv 安装依赖
uv sync

# 安装开发依赖
uv sync --group dev

# 配置环境
cp .env.example .env
# 编辑 .env 文件，填写你的设置

# 运行开发服务器
./dev.sh

⚙️ 配置

环境变量

在项目根目录创建 .env 文件：

# 核心 API 配置（必需）
UNRAID_API_URL=https://your-unraid-server-url/graphql
UNRAID_API_KEY=your_unraid_api_key

# MCP 服务器设置
UNRAID_MCP_TRANSPORT=streamable-http  # streamable-http（推荐），sse（已弃用），stdio
UNRAID_MCP_HOST=0.0.0.0
UNRAID_MCP_PORT=6970

# 日志配置
UNRAID_MCP_LOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR
UNRAID_MCP_LOG_FILE=unraid-mcp.log

# SSL/TLS 配置
UNRAID_VERIFY_SSL=true  # true, false 或 CA 捆绑包路径

# 可选：日志流配置
# UNRAID_AUTOSTART_LOG_PATH=/var/log/syslog  # 日志流资源路径

传输选项

传输描述使用场景
streamable-http基于 HTTP（推荐）兼容性最佳，性能最优
sse服务器发送事件（已弃用）仅限旧版支持
stdio标准 I/O直接集成场景

🛠️ 可用工具及资源

系统信息及状态

  • get_system_info() - 综合系统、操作系统、CPU、内存、硬件信息
  • get_array_status() - 存储阵列状态、容量和磁盘详情
  • get_unraid_variables() - 系统变量和设置
  • get_network_config() - 网络配置和访问 URL
  • get_registration_info() - Unraid 注册详情
  • get_connect_settings() - Unraid Connect 配置

Docker 容器管理

  • list_docker_containers() - 列出所有容器及其缓存选项
  • manage_docker_container(id, action) - 启动/停止容器（幂等操作）
  • get_docker_container_details(identifier) - 详细的容器信息

虚拟机管理

  • list_vms() - 列出所有虚拟机及其状态
  • manage_vm(id, action) - 虚拟机生命周期（启动/停止/暂停/恢复/重启）
  • get_vm_details(identifier) - 详细的虚拟机信息

存储及文件系统

  • get_shares_info() - 用户共享信息
  • list_physical_disks() - 物理磁盘发现
  • get_disk_details(disk_id) - SMART 数据和详细的磁盘信息

监控及诊断

  • health_check() - 综合系统健康评估
  • get_notifications_overview() - 按严重程度分类的通知数量
  • list_notifications(type, offset, limit) - 过滤通知列表
  • list_available_log_files() - 可用的系统日志
  • get_logs(path, tail_lines) - 日志文件内容检索

云存储（RClone）

  • list_rclone_remotes() - 列出已配置的远程
  • get_rclone_config_form(provider) - 配置模式
  • create_rclone_remote(name, type, config) - 创建新的远程
  • delete_rclone_remote(name) - 删除现有的远程

实时订阅及资源

  • test_subscription_query(query) - 测试 GraphQL 订阅
  • diagnose_subscriptions() - 订阅系统诊断

MCP 资源（实时数据）

  • unraid://logs/stream - 从 /var/log/syslog 实现的实时日志流，通过 WebSocket 订阅

注意：MCP 资源提供实时数据流，可以通过 MCP 客户端访问。日志流资源会自动连接到你的 Unraid 系统日志，并提供实时更新。

🔧 开发

项目结构

unraid-mcp/
├── unraid_mcp/               # 主要包
│   ├── main.py               # 入口点
│   ├── config/               # 配置管理
│   │   ├── settings.py       # 环境及设置
│   │   └── logging.py        # 日志设置
│   ├── core/                 # 核心基础设施
│   │   ├── client.py         # GraphQL 客户端
│   │   ├── exceptions.py     # 自定义异常
│   │   └── types.py          # 共享数据类型
│   ├── subscriptions/        # 实时订阅
│   │   ├── manager.py        # WebSocket 管理
│   │   ├── resources.py      # MCP 资源
│   │   └── diagnostics.py    # 诊断工具
│   ├── tools/                # MCP 工具类别
│   │   ├── docker.py         # 容器管理
│   │   ├── system.py         # 系统信息
│   │   ├── storage.py        # 存储及监控
│   │   ├── health.py         # 健康检查
│   │   ├── virtualization.py # 虚拟机管理
│   │   └── rclone.py         # 云存储
│   └── server.py             # FastMCP 服务器设置
├── logs/                     # 日志文件（自动生成）
├── dev.sh                    # 开发脚本
└── docker-compose.yml        # Docker Compose 部署

代码质量命令

# 格式化代码
uv run black unraid_mcp/

# 代码检查
uv run ruff check unraid_mcp/

# 类型检查
uv run mypy unraid_mcp/

# 运行测试
uv run pytest

开发工作流程

# 启动开发服务器（安全地终止现有进程）
./dev.sh

# 仅停止服务器
./dev.sh --kill

🏗️ 架构

核心原则

  • 模块化设计：跨专注模块分离关注点
  • 异步优先：所有操作都是非阻塞且并发安全
  • 错误弹性：全面的错误处理和优雅降级
  • 配置驱动：基于环境的配置和验证
  • 可观测性：结构化日志和健康监控

关键组件

组件目的
FastMCP 服务器MCP 协议实现和工具注册
GraphQL 客户端异步 HTTP 客户端和超时管理
订阅管理器WebSocket 连接以实现实时数据
工具模块领域特定的业务逻辑（Docker、VM 等）
配置系统环境加载和验证
日志框架结构化日志和文件轮换

🐛 故障排除

常见问题

🔥 端口已被占用

./dev.sh  # 自动终止现有进程

🔧 连接被拒绝

# 检查 Unraid API 配置
curl -k "${UNRAID_API_URL}" -H "X-API-Key: ${UNRAID_API_KEY}"

📝 导入错误

# 重新安装依赖
uv sync --reinstall

🔍 调试模式

# 启用调试日志
export UNRAID_MCP_LOG_LEVEL=DEBUG
uv run unraid-mcp-server

健康检查

# 使用内置的健康检查工具通过 MCP 客户端
# 或查看日志：logs/unraid-mcp.log

📄 许可证

此项目采用 MIT 许可证 - 详情参见 LICENSE 文件。

🤝 贡献

  1. 分叉仓库
  2. 创建功能分支：git checkout -b feature/amazing-feature
  3. 运行测试：uv run pytest
  4. 提交更改：git commit -m '添加精彩功能'
  5. 推送到分支：git push origin feature/amazing-feature
  6. 打开拉取请求

📞 支持

  • 📚 文档：查阅内联代码文档
  • 🐛 问题：GitHub 问题
  • 💬 讨论：使用 GitHub 讨论提问

为 Unraid 社区打造，充满爱心