Docker MCP Server

🚀 Docker MCP 服务器

Docker MCP 服务器是一个模型上下文协议（MCP）服务器，为 AI 助手和应用程序提供 Docker 容器执行能力。该服务器允许在容器化环境中隔离执行命令和进行文件操作。

🚀 快速开始

选项 1：使用 npx 运行（推荐）

# 直接使用 npx 运行（无需安装）
npx docker-mcp-server

# 使用自定义容器名称运行
npx docker-mcp-server --container-name my-container

# 显示帮助和可用选项
npx docker-mcp-server --help

前提条件：必须安装并运行 Docker，且有可用的容器。

选项 2：全局安装

# 全局安装
npm install -g docker-mcp-server

# 从任意位置运行
docker-mcp-server --container-name my-container

选项 3：开发环境设置

1. 克隆并设置

git clone <your-repository-url>
cd docker-mcp
npm install

2. 启动环境

# 重置并启动 Docker 环境
./reset-docker.sh

此脚本将：

• 停止所有现有的容器
• 清理 /tmp 目录
• 在后台启动容器
• 进入交互式 shell

3. 构建并运行 MCP 服务器

# 构建 TypeScript
npm run build

# 启动 MCP 服务器（使用默认容器名称：mcp-container）
npm start

# 使用自定义容器名称启动
npm start -- --container-name my-custom-container

# 或者在一个命令中构建并启动
npm run dev

# 使用自定义容器构建并启动
npm run dev -- --container-name my-custom-container

✨ 主要特性

• 安全的命令执行：在隔离的 Docker 容器中运行 shell 命令。
• 文件操作：在容器内读取、写入、编辑和搜索文件。
• 进程管理：使用唯一 ID 跟踪长时间运行的进程。
• 交互式输入：向正在运行的进程发送输入。
• 智能超时：基于输出活动进行智能进程超时处理。

🏗️ 架构

此 MCP 服务器充当 MCP 客户端（如 Claude Code）和 Docker 容器环境之间的桥梁：

MCP Client (Claude Code) ↔ MCP Server ↔ Docker Container (Debian + Node.js)
                                              ↓
                                        Host ./tmp directory

核心组件

• MCP 服务器 (src/index.ts) - 使用 @modelcontextprotocol/sdk 的 TypeScript 服务器。
• Docker 容器 - 基于 Debian 的容器，包含 Node.js 和开发工具。
• 文件挂载 - 将主机的 ./tmp 目录挂载到容器的 /app 以实现持久化。
• 进程跟踪 - 使用唯一 ID 和监控进行后台进程管理。

📋 前提条件

• 安装并运行 Docker。
• 安装 Docker Compose 以方便进行容器管理。
• 安装 Node.js（v18 或更高版本）用于 MCP 服务器。
• 安装 npm 用于依赖管理。

🔧 CLI 使用方法

MCP 服务器支持以下命令行选项：

# 显示帮助和可用选项
node dist/index.js --help

# 使用默认容器名称（mcp-container）启动
node dist/index.js

# 使用自定义容器名称启动
node dist/index.js --container-name my-dev-container
node dist/index.js -c my-dev-container

# 显示版本
node dist/index.js --version

容器名称配置

你可以通过以下几种方式配置 Docker 容器名称：

1. 默认：如果未提供选项，则使用 mcp-container。
2. CLI 参数：使用 --container-name 或 -c 标志。
3. 多实例：使用不同的容器运行多个 MCP 服务器。

# 终端 1：开发容器
npm run dev -- --container-name dev-container

# 终端 2：测试容器  
npm run dev -- --container-name test-container

# 终端 3：生产容器
npm run dev -- --container-name prod-container

⚙️ MCP 客户端配置

要将此服务器与 Claude Desktop 等 MCP 客户端一起使用，请添加以下配置：

Claude Desktop 配置

添加到你的 Claude Desktop 配置文件中： 位置：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%/Claude/claude_desktop_config.json

配置：

{
  "mcpServers": {
    "docker-mcp": {
      "command": "npx",
      "args": [
        "-y", "docker-mcp-server@latest"
      ]
    }
  }
}

使用自定义容器：

{
  "mcpServers": {
    "docker-mcp": {
      "command": "npx",
      "args": [
        "-y", "docker-mcp-server@latest",
        "--container-name", "my-dev-container"
      ]
    }
  }
}

其他 MCP 客户端

对于其他 MCP 客户端，请使用以下命令：

npx -y docker-mcp-server@latest

MCP 使用的前提条件

1. Docker 容器必须正在运行：

docker run -d --name mcp-container -v ./workspace:/app node:current-bookworm sleep infinity

2. 容器应包含你的项目文件：

• 将你的工作区目录挂载到容器的 /app。
• 确保容器中安装了必要的开发工具。

3. 添加配置后重启 Claude Desktop

验证

配置完成后，Claude Desktop 应显示 Docker MCP 服务器已连接，并可以访问所有基于容器的开发工具。

🛠️ 开发命令

容器管理

# 重置 Docker 环境（停止容器、清理 /tmp、重新启动）
./reset-docker.sh

# 在后台启动容器
docker-compose up -d

# 停止并移除容器
docker-compose down

# 进入容器的交互式 shell
docker exec -it mcp-container bash

构建和运行

# 将 TypeScript 编译为 JavaScript 到 /dist
npm run build

# 运行编译后的 MCP 服务器
npm start

# 在一个命令中构建并启动
npm run dev

🔧 可用的 MCP 工具

服务器为 MCP 客户端提供以下工具：

🚀 命令执行

execute_command

在 Docker 容器内执行 shell 命令 在容器环境中执行任何 shell 命令，并进行智能进程跟踪和超时处理。

参数：

• command（字符串） - 要在容器中执行的 shell 命令。
• rationale（字符串） - 解释为什么要执行此命令。
• maxWaitTime（数字，可选） - 在返回给代理之前等待的最大秒数（默认：20）。

特性：

• 长时间运行的进程自动后台运行。
• 基于输出活动的智能超时。
• 返回进程 ID 用于监控。
• 实时捕获输出。

check_process

按 ID 监控后台进程 检查由 execute_command 启动的后台进程的状态和输出。

参数：

• processId（字符串） - 长时间运行命令返回的进程 ID。
• rationale（字符串） - 解释为什么需要检查此进程。

返回值：

• 进程状态（运行/完成）
• 当前输出（stdout/stderr）
• 退出代码（如果已完成）
• 运行时长

send_input

向正在运行的后台进程发送输入 向等待用户输入的交互式进程发送输入数据。

参数：

• processId（字符串） - 正在运行的进程的进程 ID。
• input（字符串） - 要发送给进程的输入。
• rationale（字符串） - 解释为什么需要向此进程发送输入。
• autoNewline（布尔值，可选） - 是否自动添加换行符（默认：true）。

📁 文件操作

file_read

从容器文件系统中读取文件 通过偏移量和限制参数支持读取大文件。

参数：

• filePath（字符串） - 要读取的文件的路径（相对于容器中的 /app）。
• rationale（字符串） - 解释为什么需要读取此文件。
• offset（数字，可选） - 起始行号（从 0 开始，默认：0）。
• limit（数字，可选） - 要读取的最大行数（默认：2000）。

特性：

• 带行号的输出（cat -n 格式）
• 支持分页读取大文件
• 二进制文件检测和拒绝
• 带限制的上下文安全读取

file_write

在容器中创建或覆盖文件 在进行安全检查和目录创建的情况下将内容写入文件。

参数：

• filePath（字符串） - 要写入的文件的路径（相对于容器中的 /app）。
• content（字符串） - 要写入文件的内容。
• rationale（字符串） - 解释为什么需要写入此文件。

安全特性：

• 自动创建目录
• 报告内容长度
• 文件存在性验证
• 安全的内容传输

重要提示：在写入之前，必须先使用 file_read 了解文件的当前状态和上下文。

file_edit

在文件中进行精确的字符串替换 使用精确的字符串匹配和替换进行文件编辑，并提供备份保护。

参数：

• filePath（字符串） - 要编辑的文件的路径（相对于容器中的 /app）。
• oldString（字符串） - 要替换的精确文本。
• newString（字符串） - 替换文本。
• rationale（字符串） - 解释为什么需要编辑此文件。
• replaceAll（布尔值，可选） - 是否替换所有匹配项（默认：false）。

安全特性：

• 编辑前自动创建备份
• 需要精确的字符串匹配
• 安全文本传输的 Base64 编码
• 失败时恢复备份

重要提示：必须先使用 file_read 获取要匹配的精确文本，并了解文件的当前状态。

file_ls

使用过滤功能列出目录内容 使用智能过滤和输出限制列出文件和目录。

参数：

• path（字符串，可选） - 要列出的目录路径（默认：当前目录）。
• rationale（字符串） - 解释为什么需要列出此目录。
• ignore（字符串数组，可选） - 要忽略的 glob 模式列表。

特性：

• 内置忽略模式（node_modules、.git、dist 等）
• 详细的文件信息（权限、大小、时间戳）
• 输出限制（100 项）并带有溢出通知
• 智能模式过滤

file_grep

使用正则表达式支持搜索文件内容 使用强大的 grep 功能在文件中搜索模式，并设置结果限制。

参数：

• pattern（字符串） - 搜索模式（支持正则表达式）。
• rationale（字符串） - 解释为什么需要搜索此模式。
• path（字符串，可选） - 要搜索的目录（默认：当前目录）。
• include（字符串，可选） - 要包含的文件模式（例如，'.js'、'.{ts,tsx}'）。
• caseInsensitive（布尔值，可选） - 不区分大小写的搜索（默认：false）。
• maxResults（数字，可选） - 要返回的最大结果数（默认：100）。

特性：

• 递归目录搜索
• 文件类型过滤
• 显示行号
• 结果数量限制并带有溢出报告
• 正则表达式模式支持

📊 进程管理

命令运行时具有智能超时处理：

• 默认超时：20 秒无活动后转为后台运行。
• 最大超时：绝对限制为 10 分钟。
• 进程跟踪：后台进程获得唯一 ID 用于监控。
• 智能等待：基于输出活动而不是固定间隔。

示例进程流程

# 长时间运行的命令自动转为后台运行
process_id = execute_command("npm install", "Installing dependencies")

# 稍后检查状态
check_process(process_id, "Checking installation progress")

# 向交互式进程发送输入
send_input(process_id, "y\n", "Confirming prompt")

🔒 安全注意事项

⚠️ 重要安全提示

• 此服务器为 MCP 客户端提供直接的 Docker 容器访问权限。
• 容器可以访问主机的 ./tmp 目录。
• 命令以容器级权限运行。
• 通过主机网络模式启用网络访问。

推荐的安全实践

1. 限制容器访问：限制哪些用户可以访问 MCP 服务器。
2. 监控文件操作：定期审计 ./tmp 目录的内容。
3. 网络隔离：考虑使用自定义网络而不是主机模式。
4. 资源限制：为容器添加 CPU 和内存限制。
5. 审计日志：监控容器命令执行和文件访问。

🚨 故障排除

常见问题

容器无法启动：

# 检查 Docker 是否正在运行
docker info

# 重置环境
./reset-docker.sh

权限错误：

# 确保 tmp 目录可写
chmod 755 ./tmp

MCP 服务器连接问题：

# 检查服务器是否正在运行
npm run build && npm start

# 验证容器是否可访问
docker exec -it mcp-container echo "Hello"

容器名称错误：

# 检查你的容器是否存在
docker ps -a

# 列出所有容器以查找正确的名称
docker ps --format "table {{.Names}}\t{{.Status}}"

# 使用正确的容器名称启动
npm start -- --container-name your-actual-container-name

# 服务器将在启动时验证容器是否存在

多容器设置：

# 使用不同的名称启动额外的容器
docker run -d --name dev-container -v ./tmp:/app node:current-bookworm sleep infinity
docker run -d --name test-container -v ./tmp:/app node:current-bookworm sleep infinity

# 为每个容器运行 MCP 服务器
npm run dev -- --container-name dev-container    # 终端 1
npm run dev -- --container-name test-container   # 终端 2

进程超时：

• 调整 execute_command 中的 maxWaitTime 参数。
• 使用 check_process 监控长时间运行的操作。
• 考虑将复杂操作分解为较小的步骤。

🤝 贡献

1. 分叉仓库
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 进行更改
4. 在容器环境中进行全面测试
5. 提交更改 (git commit -m 'Add amazing feature')
6. 推送到分支 (git push origin feature/amazing-feature)
7. 打开拉取请求

开发指南

• 遵循 TypeScript 最佳实践。
• 添加全面的错误处理。
• 为所有工具操作包含理由参数。
• 使用快速和长时间运行的命令进行测试。
• 记录任何新的 MCP 工具或功能。

📦 发布到 npm

要将此包发布到 npm 以供全局使用：

前提条件

1. 在 npmjs.com 创建一个 npm 账户。
2. 登录到 npm：npm login
3. 使用你的详细信息更新 package.json：

• author：你的姓名和电子邮件
• repository：你的 GitHub 仓库 URL
• homepage：你的项目主页
• bugs：你的问题 URL

发布步骤

# 1. 更新版本（补丁/次要/主要）
npm version patch

# 2. 构建项目
npm run build

# 3. 在本地测试包
npm pack
npm install -g ./docker-mcp-server-1.0.1.tgz

# 4. 测试 npx 功能
npx docker-mcp-server --help

# 5. 发布到 npm
npm publish

# 6. 验证安装是否正常工作
npx docker-mcp-server@latest --help

发布后

• 你的包将在 https://www.npmjs.com/package/docker-mcp-server 上可用。
• 用户可以使用 npx docker-mcp-server 运行它。
• 全局安装：npm install -g docker-mcp-server

📄 许可证

本项目采用 MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件。

🙋‍♂️ 支持

• 🐛 错误报告：请打开一个包含详细重现步骤的问题。
• 💡 功能请求：打开一个包含你的用例和建议解决方案的问题。
• 📖 文档：查看 CLAUDE.md 文件以获取 AI 助手特定的指南。
• 💬 问题：打开一个讨论以获取一般问题和帮助。

---

为模型上下文协议生态系统构建 🤖