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 助手特定的指南。
• 💬 問題：打開一個討論以獲取一般問題和幫助。

---

為模型上下文協議生態系統構建 🤖