使用说明

🚀 解除MCP服务器的突袭

一个功能强大的MCP（模型上下文协议）服务器，提供了与Unraid服务器的GraphQL API交互的综合工具。

[！注意] 此存储库是 jmagar/unraid mcp 但使用当前最新的GraphQL模式。

✨ 特性

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

🚀 快速开始

先决条件

Docker和Docker Compose（推荐）
或使用Python 3.10+ 紫外线为了发展
启用GraphQL API的Unraid服务器

1.克隆存储库

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

2.配置环境

cp .env.example .env
# Edit .env with your Unraid API details

3.使用Docker部署（推荐）

# Start with Docker Compose
docker compose up -d

# View logs
docker compose logs -f unraid-mcp

或3。为发展而奔跑

# Install dependencies
uv sync

# Run development server
./dev.sh

📦 安装

🐳 Docker部署（推荐）

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

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

# Set required environment variables
export UNRAID_API_URL="http://your-unraid-server/graphql"
export UNRAID_API_KEY="your_api_key_here"

# Deploy with Docker Compose
docker compose up -d

# View logs
docker compose logs -f unraid-mcp

手动Docker构建

# Build and run manually
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

🔧 开发安装

对于开发和测试：

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

# Install dependencies with uv
uv sync

# Install development dependencies  
uv sync --group dev

# Configure environment
cp .env.example .env
# Edit .env with your settings

# Run development server
./dev.sh

⚙️ 配置

环境变量

创建 .env 项目根目录中的文件：

# Core API Configuration (Required)
UNRAID_API_URL=https://your-unraid-server-url/graphql
UNRAID_API_KEY=your_unraid_api_key

# MCP Server Settings
UNRAID_MCP_TRANSPORT=streamable-http  # streamable-http (recommended), sse (deprecated), stdio
UNRAID_MCP_HOST=0.0.0.0
UNRAID_MCP_PORT=6970

# Logging Configuration
UNRAID_MCP_LOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR
UNRAID_MCP_LOG_FILE=unraid-mcp.log

# SSL/TLS Configuration  
UNRAID_VERIFY_SSL=true  # true, false, or path to CA bundle

# Optional: Log Stream Configuration
# UNRAID_AUTOSTART_LOG_PATH=/var/log/syslog  # Path for log streaming resource

运输选项

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

🛠️ 可用工具和资源

系统信息和状态

get_system_info() -全面的系统、操作系统、CPU、内存、硬件信息
get_array_status() -存储阵列状态、容量和磁盘详细信息
get_unraid_variables() -系统变量和设置
get_network_config() -网络配置和访问URL
get_registration_info() -取消注册详细信息

存储管理

get_shares_info() -用户共享信息
list_physical_disks() -物理磁盘发现
get_disk_details(disk_id) -SMART数据和详细的磁盘信息
list_available_log_files() -可用系统日志
get_logs(path, tail_lines) -日志文件内容检索
get_share_details(name) -详细的共享信息
get_pool_details(name) -详细的池信息
get_cache_pool_details(name) -详细的缓存池信息
get_filesystem_details(path) -文件系统使用和详细信息

Docker容器管理

list_docker_containers() -列出所有具有缓存选项的容器
manage_docker_container(id, action) -启动/停止容器（幂等）
get_docker_container_details(identifier) -集装箱详细信息

虚拟机管理

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

云存储（RClone）

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

健康监测

health_check() -综合系统健康评估

连接管理

get_connect_settings() -取消RAID连接配置
get_connect_status() -连接状态
get_connect_vpn_config() -VPN配置详细信息
update_connect_settings(settings) -更新连接设置

通知

get_notifications_overview() -按严重程度列出的通知计数
list_notifications(type, offset, limit) -筛选通知列表
dismiss_notification(id) -取消通知

插件

list_plugins() -列出已安装的插件
get_plugin_details(name) -插件详细信息
manage_plugin(name, action) -安装/更新/删除插件

安全

get_security_settings() -安全配置
list_ssl_certificates() -列出SSL证书
get_certificate_details(id) -详细证书信息
update_security_settings(settings) -更新安全设置

UPS管理

get_ups_status() -UPS状态和指标
get_ups_settings() -UPS配置
update_ups_settings(settings) -更新UPS设置

实时订阅和资源

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

MCP资源（实时数据）

unraid://logs/stream -实时日志流式传输 /var/log/syslog 使用WebSocket订阅

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

🔧 发展

项目结构

unraid-mcp/
├── unraid_mcp/               # Main package
│   ├── main.py               # Entry point
│   ├── config/               # Configuration management
│   │   ├── settings.py       # Environment & settings
│   │   └── logging.py        # Logging setup
│   ├── core/                 # Core infrastructure  
│   │   ├── client.py         # GraphQL client
│   │   ├── exceptions.py     # Custom exceptions
│   │   └── types.py          # Shared data types
│   ├── subscriptions/        # Real-time subscriptions
│   │   ├── manager.py        # WebSocket management
│   │   ├── resources.py      # MCP resources
│   │   └── diagnostics.py    # Diagnostic tools
│   ├── tools/                # MCP tool categories
│   │   ├── docker.py         # Container management
│   │   ├── system.py         # System information
│   │   ├── storage.py        # Storage & monitoring
│   │   ├── health.py         # Health checks
│   │   ├── virtualization.py # VM management
│   │   ├── rclone.py         # Cloud storage
│   │   ├── connect.py        # Connect management
│   │   ├── notifications.py  # Notification management
│   │   ├── plugins.py        # Plugin management
│   │   ├── security.py       # Security management
│   │   └── ups.py            # UPS management
│   └── server.py             # FastMCP server setup
├── logs/                     # Log files (auto-created)
├── dev.sh                    # Development script  
└── docker-compose.yml        # Docker Compose deployment

代码质量命令

# Format code
uv run black unraid_mcp/

# Lint code  
uv run ruff check unraid_mcp/

# Type checking
uv run mypy unraid_mcp/

# Run tests
uv run pytest

开发工作流程

# Start development server (kills existing processes safely)
./dev.sh

# Stop server only
./dev.sh --kill

🏗️ 建筑

核心原则

模块化设计：各重点模块的关注点分开
异步优先：所有操作都是非阻塞和并发安全的
差错恢复：全面的错误处理和优雅的降级
配置驱动：基于环境的配置和验证
可观测性：结构化日志记录和健康监测

关键组件

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

🐛 故障排除

常见问题

🔥 端口已在使用中

./dev.sh  # Automatically kills existing processes

🔧 连接被拒绝

# Check Unraid API configuration
curl -k "${UNRAID_API_URL}" -H "X-API-Key: ${UNRAID_API_KEY}"

📝 导入错误

# Reinstall dependencies
uv sync --reinstall

🔍 调试模式

# Enable debug logging
export UNRAID_MCP_LOG_LEVEL=DEBUG
uv run unraid-mcp-server

健康检查

# Use the built-in health check tool via MCP client
# or check logs at: logs/unraid-mcp.log

📄 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

🤝 贡献

复刻仓库
创建要素分支： git checkout -b feature/amazing-feature
运行测试： uv run pytest
提交更改： git commit -m 'Add amazing feature'
推送到分支： git push origin feature/amazing-feature
打开拉取请求

📞 支持

📚 文档：检查内联代码文档
🐛 问题： GitHub问题
💬 讨论：使用GitHub讨论来回答问题

内置于❤️ 为Unraid社区