使用说明

Docker MCP服务器

为AI助手提供强大的Docker管理

一个全面的模型上下文协议（MCP）服务器，使Cursor、Claude Desktop和其他MCP兼容客户端等AI助手能够通过自然语言交互无缝管理Docker容器、映像、网络、卷和注册表。

为什么选择Docker MCP服务器？

零配置 -开箱即用 npx，无需安装
安全第一 -破坏性操作的两步确认
交叉平台的 -适用于Windows、Linux和macOS，具有自动Docker套接字检测功能
全面的 -Docker API全面覆盖，包括Compose、注册表和系统操作
人工智能原生 -专为具有清晰、结构化响应的AI助手而设计

特性

容器管理

全生命周期控制：创建、启动、停止、重新启动、终止和删除容器
监控：实时日志、统计和集装箱检查
高级操作：暂停/取消暂停、exec命令和资源管理

图像管理

注册表操作：拉、推、标记和删除图像
建立支持：使用完整配置从Dockerfiles构建映像
检查：详细的图像历史、图层和元数据

网络管理

网络运营：创建、删除和检查Docker网络
容器连接：连接/断开容器与网络的连接
网络发现：使用高级选项列出和过滤网络

卷管理

批量操作：创建、删除和检查卷
数据持久性：管理容器的持久存储
体积检查：详细的卷信息和装载点

系统操作

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

容器执行

命令执行：在正在运行的容器中运行命令
互动环节：创建和管理exec实例
输出流：实时命令输出和日志

注册表集成

Docker 中心：搜索存储库、列出标签、身份验证、拉取/推送图像
GitHub容器注册表（GHCR）：完全身份验证和图像管理
多注册表支持：与多个注册表无缝协作

Docker编写支持

多集装箱管理：启动、停止、重新启动组合服务
服务监控：查看组合服务的日志和状态
构建操作：使用依赖关系管理构建组合服务
配置验证：解析和验证docker-compose.yml文件

安全特性

两步确认 适用于所有破坏性操作
资源预览：查看确认前将删除的内容
双重确认方式:
- 确认参数 （默认）：适用于任何地方，简单可靠
- MCP获取API （高级）：基于表单的交互式确认，以获得更好的用户体验

安装

通过npx（推荐）

npx @alisaitteke/docker-mcp

本地安装

npm install -g @alisaitteke/docker-mcp

或者在项目中本地安装：

npm install @alisaitteke/docker-mcp

快速开始

带光标

添加到光标MCP配置中（通常在 .cursor/mcp.json 或类似）：

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

重启Cursor，开始用AI管理Docker！

使用克劳德桌面

添加到您的Claude Desktop配置中：
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- 视窗: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json

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

重启Claude Desktop，开始用AI管理Docker！

本地开发和测试

先决条件

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

设置

克隆存储库：

git clone <repository-url>
cd docker-mcp

安装依赖项：

npm install

构建项目：

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

开发工作流程

在中更改源文件 src/
构建项目：

npm run build

测试更改：

npm start
# or
npm run dev

检查TypeScript错误：

npm run typecheck

读取代码：

npm run lint

故障排除

Docker连接问题：

确保Docker守护进程正在运行： docker ps
Linux/macOS：检查Docker套接字权限： ls -la /var/run/docker.sock
视窗：确保Docker Desktop正在运行并且命名管道可访问
对于远程Docker，设置环境变量： DOCKER_HOST, DOCKER_CERT_PATH等等。
macOS：如果 /var/run/docker.sock 不存在，试试 ~/.docker/run/docker.sock （Docker桌面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桌面4.0+）
视窗: //./pipe/docker_engine （命名管道）

连接方法（按优先级顺序）

环境变量 （最高优先级）：
- 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)
平台特定默认值 （自动检测）：
- Linux： /var/run/docker.sock
- macOS： /var/run/docker.sock （或 ~/.docker/run/docker.sock 如果可用）
- 窗户： //./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 -获取exec实例详细信息

撰写工具

docker_compose_up -启动Docker Compose服务
docker_compose_down -停止并删除Docker Compose服务
docker_compose_ps -列出Docker撰写服务
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容器注册表进行身份验证
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
  }
}

查看撰写日志

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

通过确认删除资源

所有破坏性操作（删除、杀死、修剪）都支持两种确认方法：

方法1：确认参数（默认值-适用于所有地方）

第一步：预览（无需确认）

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

这将返回卷详细信息和警告消息。

步骤2：确认（确认=真）

{
  "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
  }
}

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

注：获取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 -修剪未使用的网络

测试服务器

快速测试

构建项目：

npm run build

使用测试脚本：

./test-server.sh

或手动测试：

测试Docker连接：

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

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

Docker MCP Server running on stdio

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

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

注：服务器通过stdio进行通信，因此它将等待JSON-RPC请求。按Ctrl+C退出。

手动测试步骤

启动服务器：

npm run build
npm start

在另一个终端中，使用curl进行测试（如果使用HTTP传输）或使用MCP客户端
验证Docker操作是否正常：
- 列出容器：使用 docker_list_containers 工具
- 检查系统信息：使用 docker_system_info 工具

集成测试

为了进行完整的集成测试，您需要一个MCP客户端。服务器通过stdio（标准输入/输出）进行通信，因此它被设计为与MCP兼容的客户端一起工作，例如：

光标IDE
克劳德桌面
自定义MCP客户端

调试

通过检查stderr输出启用详细日志记录。服务器将错误和状态消息写入stderr：

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

需求

Node.js 18.0.0或更高版本
Docker守护进程正在运行并可访问
支持的平台：
- Linux（x64，ARM64）
- macOS（英特尔、苹果硅）
- Windows（x64，ARM64）
对于远程Docker：正确的网络访问和TLS证书（如果使用TLS）

平台特定注意事项

Linux：需要带Unix套接字的Docker守护进程 /var/run/docker.sock
macOS：适用于Docker桌面。自动检测插座位置。
视窗：适用于Docker桌面。使用命名管道 //./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

许可证

麻省理工学院

使用MCP客户端进行测试

使用Cursor进行测试（本地开发）

如果您正在本地开发并希望使用Cursor进行测试：

构建项目：

npm run build

添加到光标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进行测试：

构建项目：

npm run build

添加到Claude桌面配置：
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- 视窗: %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检查器（CLI）进行测试

您可以使用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

贡献

欢迎投稿！请随时提交拉取请求。