内容
# mcpdockery
MCP 服务器，允许 LLM（Claude 等）直接控制本地 Docker 守护进程 — 通过自然语言运行和管理容器、镜像、卷、网络和 Compose 堆栈。
使用 [FastMCP](https://github.com/modelcontextprotocol/python-sdk) 和 [Python Docker SDK](https://docker-py.readthedocs.io/) 构建。
## 要求
- Python >= 3.14
- [Docker](https://www.docker.com/) 已安装并在本地运行（Docker Desktop、Docker Engine 等）
- Docker Compose v2 CLI（`docker compose`）可在 `PATH` 上使用 — 堆栈/组合工具所需
- [uv](https://docs.astral.sh/uv/) 用于依赖项管理
## 安装
```bash
git clone <此仓库>
cd mcpdockery
uv sync
```
这会创建 `.venv` 并安装 `uv.lock` 中固定的依赖项。
## 运行
```bash
uv run main.py
```
服务器通过 stdio 通信，因此它主要是由 MCP 客户端启动，而不是在终端中独立运行。
### 连接到 Claude Desktop / Claude Code
在 MCP 客户端的配置中添加一个条目（例如 `claude_desktop_config.json`）：
```json
{
"mcpServers": {
"mcpdockery": {
"command": "uv",
"args": ["--directory", "/绝对路径/to/mcpdockery", "run", "main.py"]
}
}
}
```
重启客户端后，以下工具对模型可用。
## 可用工具
### 容器（`containers.py`）
| 工具 | 描述 |
|---|---|
| `run_container` | 从镜像运行容器，将容器端口映射到主机端口 |
| `stop_container` | 停止正在运行的容器 |
| `container_start` | 启动已停止的容器 |
| `container_restart` | 重启容器 |
| `delete_container` | 强制删除容器（如果需要，先停止） |
| `list_containers` | 列出所有容器及其状态 |
| `container_logs` | 从容器中获取最后 N 行日志 |
| `container_stats` | 报告实时 CPU % 和内存使用情况 |
| `container_inspect` | 显示环境变量、挂载、网络 IP 和健康状态 |
| `container_exec` | 在正在运行的容器内执行 shell 命令 |
### 镜像（`images.py`）
| 工具 | 描述 |
|---|---|
| `list_images` | 列出所有本地镜像及其大小 |
| `build_image` | 从已经在磁盘上的 Dockerfile 构建镜像 |
| `push_image` | 将本地镜像标记并推送到注册表（需要事先 `docker login`） |
| `delete_image` | 强制删除本地镜像 |
### 卷和网络（`volumes.py`）
| 工具 | 描述 |
|---|---|
| `list_volumes` | 列出具有驱动器和挂载点的卷 |
| `remove_volume` | 删除卷（如果仍在使用则失败） |
| `list_networks` | 列出具有驱动器和范围的网络 |
### Compose 堆栈（`stacks.py`）
| 工具 | 描述 |
|---|---|
| `deploy_stack` | 从内联 `docker-compose.yml` 部署堆栈（`compose up -d`） |
| `stop_stack` | 停止堆栈的容器而不删除它们 |
| `remove_stack` | 停止并删除堆栈，包括其卷（`compose down -v`） |
| `list_stacks` | 列出所有 Compose 项目，包括已停止的项目 |
| `stack_status` | 显示堆栈容器的状态（`compose ps`） |
| `stack_logs` | 从堆栈中的每个容器收集日志 |
## 项目结构
```
main.py # 入口点：注册工具模块并启动 MCP 服务器
server.py # 共享 FastMCP 服务器实例
docker_client.py # 延迟单例 Docker SDK 客户端
compose_client.py # 围绕 `docker compose` CLI 的薄包装
containers.py # 容器生命周期和检查工具
images.py # 镜像构建/推送/列出/删除工具
volumes.py # 卷和网络工具
stacks.py # Compose 堆栈工具
```
## 安全注意事项
此服务器为模型提供对 Docker 守护进程的真实、无沙盒控制：
- `delete_container` 和 `delete_image` 在未经确认的情况下强制删除资源。
- `remove_stack` 删除卷（`-v`），这对于有状态数据来说是破坏性和不可逆的。
- `container_exec` 在容器内运行任意 shell 命令。
- `push_image` 使用现有的本地 Docker 凭证将镜像推送到您指向的注册表。
仅将此服务器连接到您信任的客户端/代理，并有意决定让它接触哪些容器和堆栈。
## 许可证
未指定许可证。
