🐳 Docker-MCPilotS

🌐 English | 简体中文

给 AI Agent 一双管理 Docker 的手（MCP Server）——群晖 NAS 上的容器管得好，任何装了 Docker 的机器都能用。

🤔 为什么做这个？

日常使用群晖 NAS，上面跑了几十个 Docker 容器：PT 下载、媒体服务、照片备份、代码仓库……部署新服务的时候、升级更新的时候、甚至正常跑着用着，总会遇到各种问题：容器起不来了、权限不对了、连不上网了、占用资源高了……

以前排查问题要么 SSH 进去敲命令。群晖这种 NAS 系统跟标准的 Linux 服务器差别很大，命令、路径、权限体系都是定制过的，万一敲错轻则操作失败，重则把整个 NAS 搞坏。更要命的是，NAS 上往往还跑着照片备份、文件同步这些重要功能——搞坏了可不止几个容器不能用的问题，是整个家都瘫了。

要么打开群晖那个难用的 Docker 界面，点来点去找半天。

现在 Agent 很发达了，我想：能不能让 AI 来帮我管这些容器？ 让它帮我排查问题、看看日志、启停服务，出了问题也不用心惊胆战的。

但又不能真的把 SSH 权限交给 Agent，NAS 系统太特殊了，万一出岔子代价太大。

所以就想到了 MCP（Model Context Protocol）--把 Docker 的管理能力通过 MCP 接口暴露出去，Agent 只能做我们允许的操作，不会误伤系统。本质上就是一个沙箱里的 Docker 管理工具。

🤖 本项目是通过 Vibe Coding 的方式开发的--全程与 AI 协作完成设计、编码与测试，没有手写过一行代码。如果你对这种开发方式感兴趣，欢迎交流。

✨ 能做什么？

• 🖼️ Web UI：图形化管理界面，不用 AI 也能直观查看和管理容器
• 📦 容器管理：查看列表、详情、启动、停止、重启、删除
• 📜 容器日志：看日志，支持按时间段筛选
• 📊 容器资源：CPU、内存、网络占用实时查看
• 🔍 容器诊断：进程列表、健康状态、网络连接、挂载卷
• 🌐 网络拓扑：查看所有 Docker 网络和连接的容器
• 💾 卷清单：查看所有数据卷和挂载点
• 🖥️ 系统诊断：宿主机 CPU、内存、磁盘、网络信息
• 🔐 权限控制：三种角色（管理员、操作员、观察者），可按容器设置权限
• 📦 容器执行命令：安全的 docker exec 工具，默认关闭，仅 admin 可用，支持容器范围限制

📖 怎么用？

1. 把这个 MCP Server 部署到你的 NAS 上（见 部署指南）
2. 在 AI 客户端（OpenClaw、Hermes、Trae、Cursor、Claude Code、Codex……）里添加 MCP Server，填入地址和 API Key
3. 开始对话，让 Agent 帮你管理容器

典型场景：

"帮我看看 jellyfin 容器怎么回事？怎么没起来？"

"帮我看看所有容器的 CPU 和内存占用情况"

"把 jellyfin 停一下，我要升级"

"看看最近 30 分钟的 jellyfin 日志"

"帮我看看 jellyfin 容器的网络配置，端口映射是什么"

🧰 工具容器（推荐配合 exec 使用）

如果你想用 exec_container 工具在容器内执行命令，强烈建议用专门的工具容器，不要直接在业务容器里操作。

详见 工具容器。

📚 更多文档

文档	说明
部署指南	三种部署方式、环境变量、配置文件说明
权限控制	角色说明、容器范围控制、exec 权限
工具容器	为什么要用、使用步骤、挂载说明
Web UI 使用说明	各页面功能、首次登录、状态说明

⚠️ 风险提示

使用本项目即表示你理解并接受以下风险：

1. 容器操作有风险：停止、删除容器等操作可能导致数据丢失或服务中断
2. 权限配置需谨慎：admin 角色拥有完整权限，请妥善保管 API Key
3. 仅限内网使用：默认配置仅监听本地回环地址，请勿直接暴露到公网
4. 自担风险：本项目开源提供，使用者需自行评估风险
5. 建议做好备份：对重要数据和配置做好备份，操作前确认

📄 开源协议

MIT License - 详见 LICENSE 文件。

🔗 链接

• 🐙 GitHub：https://github.com/sopyk/docker-mcpilots
• 🐛 问题反馈：https://github.com/sopyk/docker-mcpilots/issues
• 📦 镜像地址：
  • Docker Hub：sopyk/docker-mcpilots
  • GHCR：ghcr.io/sopyk/docker-mcpilots