MCP Docker Server

类别	状态
构建与持续集成
SonarQube
安全
包
技术

一个暴露Docker功能给AI助手（如Claude）的模型上下文协议（MCP）服务器。通过类型安全、有文档说明的API来管理容器、镜像、网络和卷，并带有安全控制。

快速开始：

• Claude Code（标准输入输出）：claude mcp add --transport stdio docker uvx mcp-docker@latest
• Codex（标准输入输出）：codex mcp add docker -- uvx mcp-docker@latest

特点

• 33个Docker工具：单独配置可选。完整的容器、镜像、网络、卷和系统管理
• 5个AI提示：智能故障排除、优化、网络调试和安全分析
• 2个资源模板：参数化访问容器日志和统计信息（通过resources/templates/list）
• 2种传输选项：标准输入输出（本地）和HTTP（网络部署）
• 类型安全：完全类型提示，使用Pydantic验证和mypy严格模式
• 安全控制：三级安全系统（安全/中等/破坏性），可配置限制
• 全面测试：广泛的单元、集成、端到端和模糊测试覆盖
• 持续模糊测试：集成ClusterFuzzLite以提高安全性和健壮性（符合OpenSSF评分卡）
• 现代Python：使用Python 3.11+、uv包管理器和异步优先设计

安装指南

先决条件

• 安装了Python 3.11+和Docker
• uv包管理器（由uvx自动安装）

使用Claude Code安装

在终端运行以下命令：

claude mcp add --transport stdio docker uvx mcp-docker@latest

就是这样！Docker套接字会根据您的操作系统（Windows、Linux、macOS、WSL）自动检测。

使用Claude Desktop安装

添加到您的claude_desktop_config.json：

{
  "mcpServers": {
    "docker": {
      "command": "uvx",
      "args": ["mcp-docker"]
    }
  }
}

注意：本地使用无需额外配置。Docker套接字会根据您的操作系统自动检测。

获取更新：uvx缓存包且不会自动更新。要获取最新版本：

# 运行最新版本（推荐 - 不缓存）
uvx mcp-docker@latest

# 或清除所有缓存的工具环境
uv cache prune

高级用法

HTTP传输

对于网络可访问的部署，使用HTTP传输：

# 使用HTTP传输运行
mcp-docker --transport http --host 127.0.0.1 --port 8000

生产部署：

对于生产用途，部署在反向代理（如NGINX、Caddy）后面，提供：

• HTTPS/TLS终止
• OAuth/身份验证
• 速率限制
• IP过滤

命令行选项：--transport（标准输入输出/HTTP）、--host、--port

安全

MCP Docker服务器为生产部署提供了企业级的安全性，包括OAuth认证、TLS加密、速率限制、审计日志和安全控制。

⚠️重要：容器日志可能包含恶意提示（RADE风险）。参见SECURITY.md了解威胁模型和缓解策略。

对于生产部署，参见SECURITY.md：

• 完整的安全特性指南（OAuth、TLS、IP过滤、速率限制、审计日志）
• 生产部署检查表
• 威胁模型和缓解策略
• 安全最佳实践

配置

所有环境变量（安全、服务器、传输、OAuth、速率限制、CORS）都记录在 CONFIGURATION.md中。生产强化步骤、威胁模型和部署检查表位于SECURITY.md。

文档：

• CONFIGURATION.md - 完整配置参考（所有选项）
• SECURITY.md - 安全特性和生产指南

工具概述

服务器提供了33个工具，分为5类：

容器管理（10个工具）

• docker_list_containers - 列出容器并应用过滤器
• docker_inspect_container - 获取详细容器信息
• docker_create_container - 创建新容器
• docker_start_container - 启动容器
• docker_stop_container - 平稳停止容器
• docker_restart_container - 重启容器
• docker_remove_container - 移除容器
• docker_container_logs - 获取容器日志
• docker_exec_command - 在容器内执行命令
• docker_container_stats - 获取资源使用统计信息

镜像管理（9个工具）

• docker_list_images - 列出镜像
• docker_inspect_image - 获取镜像详情
• docker_pull_image - 从注册表拉取
• docker_build_image - 从Dockerfile构建
• docker_push_image - 推送到注册表
• docker_tag_image - 标记镜像
• docker_remove_image - 移除镜像
• docker_prune_images - 清理未使用的镜像
• docker_image_history - 查看层历史

网络管理（6个工具）

• docker_list_networks - 列出网络
• docker_inspect_network - 获取网络详情
• docker_create_network - 创建网络
• docker_connect_container - 将容器连接到网络
• docker_disconnect_container - 从网络断开连接
• docker_remove_network - 移除网络

卷管理（5个工具）

• docker_list_volumes - 列出卷
• docker_inspect_volume - 获取卷详情
• docker_create_volume - 创建卷
• docker_remove_volume - 移除卷
• docker_prune_volumes - 清理未使用的卷

系统工具（3个工具）

• docker_version - 获取Docker版本信息
• docker_events - 获取Docker事件，可选时间范围和过滤器
• docker_prune_system - 清理所有未使用的资源

提示

五个提示帮助AI助手处理Docker：

• 故障排除容器 - 通过日志和配置分析诊断容器问题
• 优化容器 - 获取资源使用和安全性的优化建议
• 生成compose - 从容器或描述生成docker-compose.yml
• 调试网络 - 对容器网络问题进行深入分析，系统地进行L3-L7故障排查
• 安全审计 - 按照CIS Docker基准进行全面的安全分析，并映射合规性

资源模板

两个资源模板提供对容器数据的参数化访问（可通过resources/templates/list发现）：

• container://logs/{container_id} - 获取容器日志（最后100行）
• container://stats/{container_id} - 获取实时资源使用统计信息（CPU、内存、网络、I/O）

资源模板使用URI参数动态生成资源。客户端可以通过提供container_id来通过resources/read端点访问特定容器的数据。

安全系统

服务器实现了一个三级安全系统，具有可配置的操作模式和细粒度的工具过滤：

操作安全级别

1. 安全 - 只读操作（列表、检查、日志、统计）

   • 示例：docker_list_containers，docker_inspect_image，docker_container_logs

2. 中等 - 可改变但可逆的状态（启动、停止、创建）

   • 可修改系统状态
   • 由SAFETY_ALLOW_MODERATE_OPERATIONS控制（默认：true）
   • 示例：docker_create_container，docker_start_container，docker_pull_image

3. 破坏性 - 永久更改（移除、清理）

   • 无法轻易撤销
   • 需要SAFETY_ALLOW_DESTRUCTIVE_OPERATIONS=true
   • 可能需要确认
   • 示例：docker_remove_container，docker_prune_images，docker_system_prune

工具过滤（允许/拒绝列表）

除了安全级别外，还可以使用允许和拒绝列表精确控制哪些工具可用：

拒绝列表 - 阻止特定工具（优先于允许列表）

# 通过工具名称阻止破坏性操作
SAFETY_DENIED_TOOLS="docker_remove_container,docker_prune_images,docker_system_prune"

允许列表 - 只允许特定工具（空值 = 根据安全级别允许所有）

# 只允许只读监控工具
SAFETY_ALLOWED_TOOLS="docker_list_containers,docker_inspect_container,docker_container_logs,docker_container_stats,docker_version"

工作原理：

1. 安全级别限制首先应用（中等/破坏性设置）
2. 拒绝列表无论安全级别如何都会阻止特定工具
3. 如果非空，允许列表仅限于列出的工具
4. 工具在list_tools()和执行时被过滤

用例：

• 限制AI代理只进行只读操作以进行监控
• 在相同的安全级别下阻止特定危险工具而允许其他工具
• 为不同的用户角色或环境创建自定义工具子集
• 防止关键操作的意外执行

安全模式

使用环境变量配置安全模式：

只读模式（最安全） - 监控和可观测性

SAFETY_ALLOW_MODERATE_OPERATIONS=false
SAFETY_ALLOW_DESTRUCTIVE_OPERATIONS=false

# 可选：明确只允许监控工具
SAFETY_ALLOWED_TOOLS="docker_list_containers,docker_list_images,docker_inspect_container,docker_inspect_image,docker_container_logs,docker_container_stats,docker_version,docker_system_info"

• ✅ 列表、检查、日志、统计
• ❌ 创建、启动、停止、拉取
• ❌ 移除、清理

默认模式（平衡） - 开发和运营

SAFETY_ALLOW_MODERATE_OPERATIONS=true  # 或省略（默认）
SAFETY_ALLOW_DESTRUCTIVE_OPERATIONS=false

# 可选：仅阻止最危险的操作
SAFETY_DENIED_TOOLS="docker_system_prune,docker_prune_volumes"

• ✅ 列表、检查、日志、统计
• ✅ 创建、启动、停止、拉取
• ❌ 移除、清理

全模式（最少限制） - 基础设施管理

SAFETY_ALLOW_MODERATE_OPERATIONS=true
SAFETY_ALLOW_DESTRUCTIVE_OPERATIONS=true

• ✅ 列表、检查、日志、统计
• ✅ 创建、启动、停止、拉取
• ✅ 移除、清理

注意：只读模式适用于监控、审核和可观测性用例，不允许对Docker状态进行任何更改。

MCP服务器 vs. Docker CLI

功能	直接使用Docker CLI	MCP Docker服务器
Claude Desktop	❌ 无CLI访问	✅ 必需（唯一选择）
Claude Code	✅ 立即生效	✅ 可选（增加安全性）
设置	无需设置	安装和配置
安全控制	❌ 无	✅ 只读模式，操作阻塞
数据格式	文本（需解析）	结构化JSON
审计日志	手动设置	✅ 内置
速率限制	❌ 无	✅ 可配置
输入验证	❌ 无	✅ Pydantic模式
Docker覆盖率	100%（所有功能）	36个核心操作
复杂性	低（标准命令）	中等（MCP协议）

何时使用MCP服务器：

• 必需：Claude Desktop（无其他选择）
• 推荐：生产自动化、合规要求、多用户访问、需要安全控制

何时直接使用CLI：

• 最适合：Claude Code进行简单任务、高级Docker功能、最小设置

混合方法：使用MCP进行常见操作 + 使用CLI进行高级功能。

文档

• 安全指南 - 安全特性、TLS/HTTPS、身份验证、生产检查表

开发

设置开发环境

# 克隆仓库
git clone https://github.com/williajm/mcp_docker.git
cd mcp_docker