docker-mcp

Docker MCP 服务

一个全面的模型上下文协议（MCP）服务，让 Cursor、Claude Desktop 等 MCP 兼容客户端能够通过自然语言交互，无缝管理 Docker 容器、镜像、网络、卷和镜像仓库。

为什么选择 Docker MCP 服务？

• 零配置 - 使用 npx 即可开箱即用，无需安装
• 安全优先 - 对破坏性操作采用两步确认
• 跨平台 - 支持 Windows、Linux 和 macOS，并可自动检测 Docker 套接字
• 功能全面 - 全面覆盖 Docker API，包括 Compose、镜像仓库和系统操作
• 面向 AI 原生设计 - 专为 AI 助手打造，提供清晰、结构化的响应

功能

容器管理

• 完整生命周期控制：创建、启动、停止、重启、终止和移除容器
• 监控：实时日志、统计信息和容器检查
• 高级操作：暂停/恢复、执行命令和资源管理

镜像管理

• 镜像仓库操作：拉取、推送、标记和移除镜像
• 构建支持：通过完整配置从 Dockerfile 构建镜像
• 检查：详细的镜像历史、层和元数据

网络管理

• 网络操作：创建、移除和检查 Docker 网络
• 容器连接：将容器连接到网络或从网络断开
• 网络发现：通过高级选项列出和筛选网络

卷管理

• 卷操作：创建、移除和检查卷
• 数据持久化：管理容器的持久存储
• 卷检查：查看详细的卷信息和挂载点

系统操作

• 系统信息：Docker 守护进程信息、版本和功能
• 资源清理：清理未使用的镜像、容器、卷和网络
• 事件监控：实时 Docker 事件流

容器执行

• 命令执行：在运行中的容器内运行命令
• 交互式会话：创建和管理 exec 实例
• 输出流式传输：实时命令输出和日志

镜像仓库集成

• Docker Hub：搜索仓库、列出标签、进行身份验证，以及拉取/推送镜像
• GitHub Container Registry（GHCR）：完整的身份验证和镜像管理
• 多镜像仓库支持：无缝使用多个镜像仓库

Docker Compose 支持

• 多容器管理：启动、停止和重启 Compose 服务
• 服务监控：查看 Compose 服务的日志和状态
• 构建操作：管理依赖项并构建 Compose 服务
• 配置验证：解析并验证 docker-compose.yml 文件

安全功能

• 对所有破坏性操作进行两步确认
• 资源预览：确认前查看将要删除的内容
• 双重确认方式：
  • Confirm 参数（默认）：适用于各种场景，简单可靠
  • MCP Elicitation API（高级）：通过交互式表单确认，提供更好的用户体验

安装

通过 npx 安装（推荐）

npx @alisaitteke/docker-mcp

本地安装

npm install -g @alisaitteke/docker-mcp

也可以在项目中本地安装：

npm install @alisaitteke/docker-mcp

快速开始

使用 Cursor

1. 将配置添加到 Cursor MCP 配置中（通常位于 .cursor/mcp.json 或类似路径）：

{
  "mcpServers": {
    "docker": {
      "command": "npx",
      "args": ["@alisaitteke/docker-mcp"]
    }
  }
}

2. 重启 Cursor，即可开始使用 AI 管理 Docker！

使用 Claude Desktop

1. 将配置添加到 Claude Desktop 配置文件中：
   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • Linux：~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "docker": {
      "command": "npx",
      "args": ["@alisaitteke/docker-mcp"]
    }
  }
}

2. 重启 Claude Desktop，即可开始使用 AI 管理 Docker！

本地开发与测试

前提条件

• Node.js 18.0.0 或更高版本
• Docker 守护进程正在运行
• npm 或 yarn

设置

1. 克隆仓库：

git clone <repository-url>
cd docker-mcp

2. 安装依赖：

npm install

3. 构建项目：

npm run build

本地运行

方法 1：使用 npm start（构建后）

# Build first
npm run build

# Run the server
npm start

方法 2：使用 npm run dev（通过 tsx 进入开发模式）

npm run dev

此方法使用 tsx 直接运行 TypeScript，无需构建。

方法 3：直接执行

# Build first
npm run build

# Run directly with node
node dist/index.js

方法 4：使用二进制文件

# Build first
npm run build

# Make sure the binary is executable
chmod +x bin/docker-mcp-server.js

# Run the binary
./bin/docker-mcp-server.js

开发工作流

1. 修改 src/ 中的源文件
2. 构建项目：

npm run build

3. 测试更改：

npm start
# or
npm run dev

4. 检查 TypeScript 错误：

npm run typecheck

5. 检查代码规范：

npm run lint

故障排除

Docker 连接问题：

• 确保 Docker 守护进程正在运行：docker ps
• Linux/macOS：检查 Docker 套接字权限：ls -la /var/run/docker.sock
• Windows：确保 Docker Desktop 正在运行，且命名管道可访问
• 对于远程 Docker，请设置环境变量：DOCKER_HOST、DOCKER_CERT_PATH 等
• macOS：如果 /var/run/docker.sock 不存在，请尝试使用 ~/.docker/run/docker.sock（Docker Desktop 4.0+）

构建错误：

• 清除 node_modules 并重新安装：rm -rf node_modules && npm install
• 检查 TypeScript 版本兼容性
• 确保已安装所有依赖：npm install

运行时错误：

• 检查 Docker 是否可访问：docker version
• 确认构建成功：ls -la dist/
• 检查服务日志（错误会写入 stderr）

配置

服务会自动检测操作系统，并使用相应的 Docker 套接字路径：

平台特定默认值

• Linux：/var/run/docker.sock（Unix 套接字）
• macOS：/var/run/docker.sock 或 ~/.docker/run/docker.sock（Docker Desktop 4.0+）
• Windows：//./pipe/docker_engine（命名管道）

连接方式（按优先级排序）

1. 环境变量（最高优先级）：

   • DOCKER_HOST - Docker 守护进程主机（例如：tcp://localhost:2376、npipe:////./pipe/docker_engine）
   • DOCKER_PORT - Docker 守护进程端口
   • DOCKER_PROTOCOL - 协议（http 或 https）
   • DOCKER_SOCKET_PATH - Docker 套接字路径（覆盖平台默认值）
   • DOCKER_CERT_PATH - Docker 证书目录路径
   • DOCKER_TLS_VERIFY - 启用 TLS 验证（1 或 0）

2. 平台特定默认值（自动检测）：

   • Linux：/var/run/docker.sock
   • macOS：/var/run/docker.sock（如果存在，则使用 ~/.docker/run/docker.sock）
   • Windows：//./pipe/docker_engine

Windows 配置

在 Windows 上，Docker Desktop 使用命名管道。服务会自动检测 Windows 并使用正确的路径。你也可以显式设置：

# Using environment variable
set DOCKER_SOCKET_PATH=//./pipe/docker_engine

# Or using DOCKER_HOST
set DOCKER_HOST=npipe:////./pipe/docker_engine

远程 Docker 主机

连接到远程 Docker 主机：

# Linux/macOS
export DOCKER_HOST=tcp://192.168.1.100:2376
export DOCKER_TLS_VERIFY=1
export DOCKER_CERT_PATH=/path/to/certs

# Windows
set DOCKER_HOST=tcp://192.168.1.100:2376
set DOCKER_TLS_VERIFY=1
set DOCKER_CERT_PATH=C:\path\to\certs

可用工具

容器工具

• docker_list_containers - 列出所有容器
• docker_create_container - 创建新容器
• docker_start_container - 启动容器
• docker_stop_container - 停止容器
• docker_restart_container - 重启容器
• docker_kill_container - 强制终止容器
• docker_remove_container - 移除容器
• docker_inspect_container - 获取容器详细信息
• docker_container_logs - 获取容器日志
• docker_container_stats - 获取容器统计信息
• docker_pause_container - 暂停容器
• docker_unpause_container - 恢复容器

镜像工具

• docker_list_images - 列出所有镜像
• docker_pull_image - 从仓库拉取镜像
• docker_push_image - 将镜像推送到仓库
• docker_tag_image - 为镜像添加标签
• docker_remove_image - 移除镜像
• docker_inspect_image - 获取镜像详细信息
• docker_image_history - 获取镜像历史记录

网络工具

• docker_list_networks - 列出所有网络
• docker_create_network - 创建网络
• docker_remove_network - 移除网络
• docker_inspect_network - 获取网络详细信息
• docker_connect_container - 将容器连接到网络
• docker_disconnect_container - 断开容器与网络的连接

卷工具

• docker_list_volumes - 列出所有卷
• docker_create_volume - 创建卷
• docker_remove_volume - 移除卷
• docker_inspect_volume - 获取卷详细信息

系统工具

• docker_system_info - 获取 Docker 系统信息
• docker_version - 获取 Docker 版本
• docker_prune_system - 清理所有未使用的资源
• docker_prune_images - 清理未使用的镜像
• docker_prune_containers - 清理已停止的容器
• docker_prune_volumes - 清理未使用的卷
• docker_prune_networks - 清理未使用的网络

执行工具

• docker_exec - 在容器中执行命令
• docker_inspect_exec - 获取执行实例详细信息

Compose 工具

• docker_compose_up - 启动 Docker Compose 服务
• docker_compose_down - 停止并移除 Docker Compose 服务
• docker_compose_ps - 列出 Docker Compose 服务
• docker_compose_logs - 查看 Docker Compose 服务的输出
• docker_compose_config - 解析并验证 docker-compose.yml 文件
• docker_compose_build - 构建 Docker Compose 服务
• docker_compose_restart - 重启 Docker Compose 服务
• docker_compose_stop - 停止 Docker Compose 服务
• docker_compose_start - 启动 Docker Compose 服务

镜像仓库工具

• dockerhub_search - 搜索 Docker Hub
• dockerhub_get_tags - 获取 Docker Hub 仓库标签
• dockerhub_authenticate - 验证 Docker Hub 身份
• dockerhub_pull - 从 Docker Hub 拉取镜像
• dockerhub_push - 推送镜像到 Docker Hub
• ghcr_authenticate - 验证 GitHub Container Registry 身份
• ghcr_pull - 从 GHCR 拉取镜像
• ghcr_push - 推送镜像到 GHCR

示例

列出正在运行的容器

{
  "name": "docker_list_containers",
  "arguments": {
    "all": false
  }
}

创建并启动容器

{
  "name": "docker_create_container",
  "arguments": {
    "image": "nginx:latest",
    "name": "my-nginx",
    "ports": {"80/tcp": {}}
  }
}

然后启动它：

{
  "name": "docker_start_container",
  "arguments": {
    "id": "my-nginx"
  }
}

从 Docker Hub 拉取镜像

{
  "name": "docker_pull_image",
  "arguments": {
    "name": "ubuntu:20.04"
  }
}

搜索 Docker Hub

{
  "name": "dockerhub_search",
  "arguments": {
    "query": "node",
    "limit": 10
  }
}

在容器中执行命令

{
  "name": "docker_exec",
  "arguments": {
    "containerId": "my-container",
    "cmd": ["ls", "-la"],
    "tty": false
  }
}

启动 Docker Compose 服务

{
  "name": "docker_compose_up",
  "arguments": {
    "projectDir": "/path/to/compose/project",
    "detach": true,
    "build": true
  }
}

查看 Compose 日志

{
  "name": "docker_compose_logs",
  "arguments": {
    "projectDir": "/path/to/compose/project",
    "follow": false,
    "tail": 100
  }
}

确认后移除资源

所有破坏性操作（移除、强制终止、清理）都支持两种确认方式：

方法 1：确认参数（默认方式——适用于所有环境）

步骤 1：预览（不确认）

{
  "name": "docker_remove_volume",
  "arguments": {
    "name": "my-volume"
  }
}

这会返回卷详情和警告消息。

步骤 2：确认（使用 confirm=true）

{
  "name": "docker_remove_volume",
  "arguments": {
    "name": "my-volume",
    "confirm": true
  }
}

这会实际删除该卷。

方法 2：MCP Elicitation API（高级方式——用户体验更佳）

如果你的 MCP 客户端（Cursor、Claude Desktop）支持 Elicitation API，你可以使用交互式确认：

{
  "name": "docker_remove_volume",
  "arguments": {
    "name": "my-volume",
    "useElicitation": true
  }
}

这会在客户端中显示交互式确认对话框（如果客户端支持）。客户端会显示一个要求确认的表单，只有用户接受后才会继续执行操作。

**注意：**是否支持 Elicitation API 取决于 MCP 客户端。如果客户端不支持，服务会自动回退到 confirm 参数方式。

需要确认的操作：

• docker_remove_volume - 删除卷
• docker_remove_container - 删除容器
• docker_kill_container - 终止容器
• docker_remove_image - 删除镜像
• docker_remove_network - 删除网络
• docker_prune_system - 清理所有未使用的资源
• docker_prune_images - 清理未使用的镜像
• docker_prune_containers - 清理已停止的容器
• docker_prune_volumes - 清理未使用的卷
• docker_prune_networks - 清理未使用的网络

测试服务

快速测试

1. 构建项目：

npm run build

2. 使用测试脚本：

./test-server.sh

也可以手动测试：

3. 测试 Docker 连接：

# The server will exit with error if Docker is not accessible
node dist/index.js

如果 Docker 正在运行，你应该会看到：

Docker MCP Server running on stdio

4. 使用简单的 MCP 请求进行测试（使用 jq 格式化 JSON）：

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/index.js | jq

**注意：**服务通过 stdio 通信，因此会等待 JSON-RPC 请求。按 Ctrl+C 退出。

手动测试步骤

1. 启动服务：

npm run build
npm start

2. 在另一个终端中使用 curl 测试（如果使用 HTTP 传输），或使用 MCP 客户端

3. 验证 Docker 操作是否正常：

   • 列出容器：使用 docker_list_containers 工具
   • 检查系统信息：使用 docker_system_info 工具

集成测试

要进行完整的集成测试，你需要一个 MCP 客户端。服务通过 stdio（标准输入/输出）通信，因此专为与兼容 MCP 的客户端配合使用而设计，例如：

• Cursor IDE
• Claude Desktop
• 自定义 MCP 客户端

调试

查看 stderr 输出以启用详细日志记录。服务会将错误和状态消息写入 stderr：

# Run and capture stderr
node dist/index.js 2> debug.log

要求

• Node.js 18.0.0 或更高版本
• Docker 守护进程正在运行且可访问
• 支持的平台：
  • Linux（x64、ARM64）
  • macOS（Intel、Apple Silicon）
  • Windows（x64、ARM64）
• 对于远程 Docker：需要适当的网络访问权限和 TLS 证书（如果使用 TLS）

特定平台说明

• Linux：需要使用位于 /var/run/docker.sock 的 Unix 套接字连接 Docker 守护进程
• macOS：可与 Docker Desktop 配合使用。会自动检测套接字位置。
• Windows：可与 Docker Desktop 配合使用。使用命名管道 //./pipe/docker_engine

快速开始（本地开发）

# Clone and setup
git clone <repository-url>
cd docker-mcp
npm install

# Build
npm run build

# Test
./test-server.sh

# Run
npm start
# or for development
npm run dev

许可证

MIT

使用 MCP 客户端进行测试

使用 Cursor 测试（本地开发）

如果你正在本地开发并想使用 Cursor 测试：

1. 构建项目：

npm run build

2. 添加到 Cursor MCP 配置中（通常位于 .cursor/mcp.json 或类似位置）：

{
  "mcpServers": {
    "docker": {
      "command": "node",
      "args": ["/absolute/path/to/docker-mcp/dist/index.js"]
    }
  }
}

如果使用二进制文件：

{
  "mcpServers": {
    "docker": {
      "command": "/absolute/path/to/docker-mcp/bin/docker-mcp-server.js"
    }
  }
}

使用 Claude Desktop 测试（本地开发）

如果你正在本地开发并想使用 Claude Desktop 测试：

1. 构建项目：

npm run build

2. 添加到 Claude Desktop 配置中：
   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • Linux：~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "docker": {
      "command": "node",
      "args": ["/absolute/path/to/docker-mcp/dist/index.js"]
    }
  }
}

使用 MCP Inspector 测试（命令行）

你可以使用 MCP Inspector 或任何 MCP 客户端测试该服务：

# Build first
npm run build

# The server communicates via stdio, so you can pipe commands to it
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/index.js

贡献

欢迎贡献！欢迎提交 Pull Request。