unraid ssh mcp
A. 装有护栏的 MCP服务器，为Claude（或任何MCP客户端）提供对Unraid服务器的SSH访问权限，并内置安全控制。
服务器没有公开原始shell，而是为Docker管理、文件操作和系统监控提供了专门构建的工具。危险的命令在到达服务器之前就被阻止了。
为什么？
官方的 unraid mcp 服务器使用GraphQL API，涵盖阵列运行状况、磁盘状态和基本容器启动/停止，但它 不能 跑 docker exec，查看容器环境变量、读取日志文件或编辑配置。
这台服务器通过SSH填补了这个空白，并配有护栏，这样克劳德就不会意外 rm -rf / 你的闪存盘。
______________________________________________________________________
特性
Docker工具
| 工具 | 说明 |
|---|---|
docker_exec | 在容器内运行命令 |
docker_exec_it | 运行交互式命令（使用伪TTY） |
docker_logs | 查看容器日志（带尾部/尾部） |
docker_inspect | 完整的容器详细信息，包括环境变量、端口、挂载 |
docker_start | 启动已停止的容器 |
docker_stop | 停止正在运行的容器 |
docker_restart | 重新启动容器 |
docker_stats | 所有容器的实时资源使用情况 |
docker_cp | 在容器和主机之间复制文件 |
文件系统工具
| 工具 | 说明 |
|---|---|
read_file | 读取文件（阻止敏感路径） |
write_file | 仅写入允许的路径(/mnt/user, /tmp等等） |
list_directory | 列出目录内容 |
find_files | 按名称模式搜索文件 |
系统工具
| 工具 | 说明 |
|---|---|
system_overview | 正常运行时间、CPU、内存、磁盘使用率、顶级进程 |
run_command | 配备全护栏的总指挥部 |
tail_log | 跟踪日志文件 |
______________________________________________________________________
安全模型
在主机上被阻止
这些命令是 从不 在Unraid主机上执行：
- 破坏性的:
rm,rmdir,shred,dd,mkfs - 系统电源:
shutdown,reboot,poweroff,halt - 防火墙:
iptables,ip6tables,nftables - 用户管理:
passwd,useradd,userdel - 包裹:
installpkg,removepkg,slackpkg - 权限:
chmod,chown,chgrp - 磁盘操作:
fdisk,parted,mdadm,mount,umount
阻塞模式
- 写给
/boot（卸载闪存驱动器）或/dev rm -rf以任何形式- 叉式炸弹
- 向破坏性命令输送管道
路径限制
| 操作 | 允许 | 阻止 |
|---|---|---|
| 阅读 | 大多数路径 | /etc/shadow, /boot/config/shadow, /boot/config/smbpasswd |
| 写 | /mnt/user, /mnt/cache, /mnt/disk, /tmp | /boot, /etc, /usr, /bin, /dev, /proc, /sys |
集装箱内部
命令通过运行 docker_exec 是 更宽容 因为容器是隔离的。只有普遍的危险（分叉炸弹、设备写入）被阻止。
输出限制
命令输出上限为 64 KB 以防止上下文窗口爆裂。超大输出显示第一部分和最后一部分。
______________________________________________________________________
安装
先决条件
- 紫外线 已安装在本地计算机上
- 在Unraid服务器上启用SSH（设置→ 管理访问→ SSH)
- 您的Unraid root密码
设置
- 克隆仓库：
git clone https://github.com/YOUR_USERNAME/unraid-ssh-mcp.git
cd unraid-ssh-mcp- 创建您的
.env文件：
cp .env.example .env编辑 .env 使用您的Unraid SSH凭据：
SSH_HOST=192.168.0.150
SSH_PORT=22
SSH_USER=root
SSH_PASSWORD=your-password-here- 安装依赖项：
uv sync- 测试其工作原理：
uv run unraid-ssh-mcp（它将启动stdio上的MCP服务器--按Ctrl+C停止。）
______________________________________________________________________
Claude桌面配置
将此添加到您的 claude_desktop_config.json:
视窗 — %APPDATA%\Claude\claude_desktop_config.json macOS — ~/Library/Application Support/Claude/claude_desktop_config.json
{
"mcpServers": {
"unraid-ssh": {
"command": "C:\\Users\\YOUR_USER\\.local\\bin\\uv.exe",
"args": [
"run",
"--directory",
"C:\\Users\\YOUR_USER\\Desktop\\Nick's Projects\\unraid-ssh-mcp",
"unraid-ssh-mcp"
],
"env": {
"SSH_HOST": "192.168.0.150",
"SSH_PORT": "22",
"SSH_USER": "root",
"SSH_PASSWORD": "your-password-here"
}
}
}
}提示： 您可以将凭据放入env块（如上所述）或.env项目目录中的文件。这个env块优先。
保存后重新启动Claude Desktop。这个 unraid-ssh 工具应出现在MCP工具菜单中(🔌 图标）。
______________________________________________________________________
示例用法
You: What environment variables does the n8n container have?
Claude: [calls docker_inspect("n8n")]
You: Check the last 50 lines of syslog
Claude: [calls tail_log("/var/log/syslog", 50)]
You: What's using the most CPU right now?
Claude: [calls system_overview()]
You: Run `ip addr` on the server
Claude: [calls run_command("ip addr")]
You: How much memory is each container using?
Claude: [calls docker_stats()]______________________________________________________________________
定制护栏
阻止列表和路径限制存在于 src/unraid_ssh_mcp/guardrails.py。您可以编辑它们以满足您的需求：
BLOCKED_HOST_COMMANDS--主机上阻止的命令名集BLOCKED_PATTERNS--正则表达式模式处处受阻BLOCKED_HOST_PATTERNS--正则表达式模式仅在主机上被阻止BLOCKED_READ_PATHS--无法读取的路径BLOCKED_WRITE_PATHS--无法写入的路径ALLOWED_WRITE_PATHS--路径 *能* 被写入
______________________________________________________________________
建筑
Claude Desktop
│
▼ (MCP / stdio)
unraid-ssh-mcp
│
├── guardrails.py ← validates every command before execution
├── ssh_client.py ← persistent SSH connection with auto-reconnect
└── server.py ← MCP tool definitions
│
▼ (SSH)
Unraid Server (root@192.168.0.150)______________________________________________________________________
配套：unraid mcp（GraphQL）
该项目旨在与 unraid mcp 其提供：
- 阵列运行状况和磁盘状态
- 通过Unraid API启动/停止容器
- 通知管理
- 虚拟机管理
unraid ssh mcp 添加缺失的部分： docker exec、环境变量、文件操作和主机级命令。
______________________________________________________________________
许可证
麻省理工学院