Docker Mcp Server

开发 TypeScript

🚀 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 
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 容器名称：

默认：如果未提供选项，则使用 mcp-container。
CLI 参数：使用 --container-name 或 -c 标志。
多实例：使用不同的容器运行多个 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 使用的前提条件

Docker 容器必须正在运行：

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

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

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

添加配置后重启 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 目录。

命令以容器级权限运行。

通过主机网络模式启用网络访问。

🚨 故障排除

常见问题

容器无法启动：

# 检查 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 监控长时间运行的操作。
考虑将复杂操作分解为较小的步骤。

🤝 贡献

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

开发指南

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

📦 发布到 npm

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

前提条件

在 npmjs.com 创建一个 npm 账户。
登录到 npm：npm login
使用你的详细信息更新 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 助手特定的指南。
💬 问题：打开一个讨论以获取一般问题和帮助。

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

0 条评论
分类：开发