![Docker-MCPilotS Banner](web/static/assets/banner.jpg)

# 🐳 Docker-MCPilotS

> 🌐 [English](README_EN.md) | 简体中文

给 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 上（见 [部署指南](docs/guides/部署指南.md)）
2. 在 AI 客户端（OpenClaw、Hermes、Trae、Cursor、Claude Code、Codex……）里添加 MCP Server，填入地址和 API Key
3. 开始对话，让 Agent 帮你管理容器

**典型场景：**

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

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

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

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

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

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

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

详见 [工具容器](docs/guides/工具容器.md)。

## 📚 更多文档

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

## ⚠️ 风险提示

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

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

## 📄 开源协议

MIT License - 详见 [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`