内容
# Docker 容器管理器 MCP 服务器
> 一个 MCP 服务器，允许任何 LLM 客户端列出、检查、启动、停止和监控主机上的 Docker 容器 — 将您的整个容器堆栈置于 AI 助手的指尖。
---
## 概述
该服务器使用 [FastMCP](https://gofastmcp.com) 包装 [Docker SDK for Python](https://docker-py.readthedocs.io/en/stable/)，将容器管理操作作为工具暴露给任何 MCP 兼容的客户端调用。将其连接到 Claude Desktop，您可以要求 Claude 检查容器健康状况、获取日志、检查配置或监控实时 CPU 和内存使用情况 — 所有这些都来自单个对话。
服务器在启动时通过 Unix 套接字连接到 Docker 守护进程，验证连接性并通过 FastMCP 的生命周期上下文在所有工具调用之间共享客户端。不需要令牌 — 只需要一个正在运行的 Docker 守护进程。
---
## 工具
| 工具 | 描述 |
|---|---|
| `list_containers` | 列出正在运行或所有容器及其状态和端口映射 |
| `start_container` | 按名称或 ID 启动停止的容器 |
| `stop_container` | 正常停止正在运行的容器 |
| `get_container_logs` | 获取最后 N 行的时间戳日志 |
| `inspect_container` | 获取完整的容器详细信息 — 镜像、环境变量、挂载、网络 |
| `get_container_stats` | 获取实时 CPU 和内存使用情况，匹配 `docker stats` 输出 |
---
## 项目结构
```
docker-manager-mcp/
├── server.py # FastMCP 实例、生命周期、工具注册
├── config.py # 环境变量和常量
├── tools/
│ ├── __init__.py
│ ├── containers.py # list、start、stop、logs、inspect
│ └── stats.py # get_container_stats，具有准确的 CPU/内存计算
├── .env # 可选覆盖
├── .env.example # 模板
├── requirements.txt
├── Dockerfile
└── README.md
```
---
## 需求
- Python 3.11+
- [uv](https://docs.astral.sh/uv/getting-started/installation/)
- Docker 在主机上运行
- 您的用户在 `docker` 组中：`sudo usermod -aG docker $USER`
---
## 设置
**1. 克隆仓库：**
```bash
git clone https://github.com/Festuskipkoech/docker-manager-mcp.git
cd docker-manager-mcp
```
**2. 安装依赖项：**
```bash
uv sync
```
**3. 配置环境（可选）：**
```bash
cp .env.example .env
```
默认值在 Linux 和 macOS 上开箱即用。不需要令牌或凭证。
```
DOCKER_HOST=unix:///var/run/docker.sock
DEFAULT_LOG_LINES=50
DEFAULT_STOP_TIMEOUT=10
```
---
## 在本地运行
```bash
uv run python server.py
```
或使用 FastMCP CLI 在 Streamable HTTP 传输上：
```bash
fastmcp run server.py:mcp --transport streamable-http
```
---
## 使用 MCP Inspector 测试
在一个终端中启动服务器：
```bash
fastmcp run server.py:mcp --transport streamable-http
```
在另一个终端中启动 Inspector：
```bash
npx -y @modelcontextprotocol/inspector
```
在 Inspector UI 中：
- **传输：** Streamable HTTP
- **URL：** `http://127.0.0.1:8000/mcp`
- 点击 **连接**
**推荐的测试序列：**
| 步骤 | 工具 | 输入 |
|---|---|---|
| 1 | `list_containers` | `{"all_containers": false}` |
| 2 | `get_container_logs` | `{"container_name": "your_container", "lines": 20}` |
| 3 | `inspect_container` | `{"container_name": "your_container"}` |
| 4 | `get_container_stats` | `{"container_name": "your_container"}` |
| 5 | `stop_container` | `{"container_name": "your_container"}` |
| 6 | `start_container` | `{"container_name": "your_container"}` |
---
## 与 Claude Desktop 一起使用
将以下内容添加到 `~/.config/Claude/claude_desktop_config.json`：
```json
{
"mcpServers": {
"docker-manager": {
"command": "/home/your-user/.local/bin/uv",
"args": [
"run",
"--directory",
"/absolute/path/to/docker-manager-mcp",
"python",
"server.py"
]
}
}
}
```
使用 `uv` 的完整路径（使用 `which uv` 查找）。保存后重启 Claude Desktop，然后尝试：
```
列出我所有正在运行的 Docker 容器并显示它们的状态和端口
```
Claude 调用 `list_containers` 并返回您的完整容器堆栈：
检查容器并检查实时资源使用情况：
```
检查 prepwise_postgres 容器并显示其 CPU 和内存使用情况
```
---
## 使用 Docker 运行
当服务器本身在容器中运行时，请挂载 Docker 套接字，以便它可以访问主机守护进程：
```bash
docker build -t docker-manager-mcp .
docker run -v /var/run/docker.sock:/var/run/docker.sock -p 8000:8000 docker-manager-mcp
```
---
## 故障排除
| 错误 | 原因 | 修复 |
|---|---|---|
| `无法连接到 Docker 守护进程` | Docker 未运行或套接字不可访问 | 运行 `docker ps` 以验证 Docker 是否已启动 |
| `套接字权限被拒绝` | 用户不在 docker 组中 | 运行 `sudo usermod -aG docker $USER` 然后注销并重新登录 |
| `容器未找到` | 名称或 ID 错误 | 运行 `list_containers` 并设置 `all_containers: true` 以查看所有容器 |
| `统计信息仅适用于正在运行的容器` | 容器已停止 | 首先使用 `start_container` 启动容器 |
