内容
# Dockhand
一个 [MCP](https://modelcontextprotocol.io/) 服务器，允许大型语言模型（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` 中使用 - 堆栈/Compose工具所需
- [uv](https://docs.astral.sh/uv/) 用于依赖管理
## 安装
```bash
git clone <此仓库>
cd dockhand
uv sync
```
这会创建一个 `.venv` 并安装 `uv.lock` 中固定的依赖项。
## 运行
```bash
uv run main.py
```
服务器通过标准输入/输出通信，因此它需要由MCP客户端启动，而不是在终端中独立运行。
### 连接到Claude Desktop / Claude Code
在MCP客户端的配置文件中添加一个条目（例如 `claude_desktop_config.json`）：
```json
{
"mcpServers": {
"dockhand": {
"command": "uv",
"args": ["--directory", "/dockhand的绝对路径", "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凭证，将镜像推送到指定的注册表。
仅将此服务器连接到受信任的客户端/代理，并有选择性地让其接触哪些容器和堆栈。
## 许可证
未指定许可证。
