Docker MCP

🚀 Docker Manager MCP

Docker Manager MCP 可讓你從一處控制所有 Docker 主機。藉助它，AI 助手能夠管理容器、部署堆棧並監控整個基礎設施中的服務，而且無需任何配置。

🚀 快速開始

你可以使用以下一鍵安裝命令：

curl -sSL https://raw.githubusercontent.com/jmagar/docker-mcp/main/install.sh | bash

安裝程序會自動完成以下操作：

• ✅ 自動設置 SSH 密鑰
• ✅ 從 SSH 配置中導入所有現有主機
• ✅ 配置安全認證
• ✅ 在端口 8000 上啟動服務

無需手動配置。只要你能通過 SSH 連接到主機，Docker Manager 就能對其進行控制。

✨ 主要特性

• 跨多 Docker 主機部署應用程序：可以輕鬆地在多個 Docker 主機上部署應用，提高部署效率。
• 控制容器：支持對容器進行啟動、停止、重啟等操作，方便管理容器的生命週期。
• 監控服務：通過即時日誌流監控服務狀態，及時發現問題。
• 管理堆棧：使用 Docker Compose 配置管理堆棧，簡化堆棧管理流程。
• 無停機更新服務：利用滾動更新功能，在不中斷服務的情況下更新服務。
• 檢查端口使用情況：避免端口衝突，確保服務正常運行。
• 自動發現主機：從 SSH 配置中自動發現主機，減少手動配置的工作量。

📦 安裝指南

使用以下命令進行一鍵安裝：

curl -sSL https://raw.githubusercontent.com/jmagar/docker-mcp/main/install.sh | bash

安裝完成後，服務將在端口 8000 上啟動。

💻 使用示例

基礎用法

以下是一些使用 Docker Manager MCP 的自然語言示例：

"Add a new Docker host called production-1 at 192.168.1.100 with user dockeruser"
"List all my Docker hosts"
"Show info for the nginx container on production-1"

高級用法

部署 WordPress 站點

# compose_content for WordPress deployment
version: '3.8'
services:
  wordpress:
    image: wordpress:latest
    ports:
      - "80:80"
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_PASSWORD: secret
  db:
    image: mysql:5.7
    environment:
      MYSQL_ROOT_PASSWORD: secret
    volumes:
      - db_data:/var/lib/mysql
volumes:
  db_data:

使用以下命令部署 WordPress 堆棧：

"Deploy wordpress stack to production-1 with this compose file"

📚 詳細文檔

🛠 三個工具介紹

Tool 1: docker_hosts

這是一個簡化的 Docker 主機管理工具，支持以下操作：

• list：列出所有配置的 Docker 主機
• add：添加新的 Docker 主機（自動運行 test_connection 和 discover）
• ports：列出或檢查主機上的端口使用情況
• import_ssh：從 SSH 配置中導入主機（為每個主機自動運行 test_connection 和 discover）
• cleanup：執行 Docker 系統清理操作
• test_connection：測試主機連接性（也會運行 discover）
• discover：發現主機上的路徑和功能
• edit：修改主機配置
• remove：從配置中移除主機
• disk_usage：只讀的 Docker 磁盤使用情況摘要

Tool 2: docker_container

這是一個整合的 Docker 容器管理工具，支持以下操作：

• list：列出主機上的容器
• info：獲取容器信息
• start：啟動容器
• stop：停止容器
• restart：重啟容器
• remove：移除容器
• logs：獲取容器日誌
• pull：將容器鏡像拉取到主機上

Tool 3: docker_compose

這是一個整合的 Docker Compose 堆棧管理工具，支持以下操作：

• list：列出主機上的堆棧
• view：查看堆棧的 compose 文件
• deploy：部署堆棧
• up/down/restart/build/pull：管理堆棧的生命週期
• ps：顯示堆棧服務（狀態和端口）
• discover：發現主機上的 compose 路徑
• logs：獲取堆棧日誌
• migrate：在主機之間遷移堆棧

🏗 架構設計：為何採用三個整合工具？

Docker Manager MCP 使用 整合操作 - 參數模式 而非 27 個單獨的工具，這種架構選擇具有以下優勢：

• 令牌效率：我們的 3 個工具使用約 5k 令牌，而 27 個單獨的工具使用約 9.7k 令牌，效率提高了 2.6 倍。此外，向現有工具添加新操作比創建新工具更高效，並且每個工具添加約 400 - 500 令牌，整合減少了這種乘法效應。
• 複雜操作支持：Docker 管理需要複雜的多步驟操作，如遷移、清理和部署等，整合工具能夠更好地支持這些操作。
• 混合連接模型：不同的操作需要不同的方法，容器操作使用 Docker 上下文（通過 SSH 隧道的 API）以提高效率，堆棧操作使用直接 SSH（文件系統訪問）以管理 compose 文件。
• 服務層優勢：提供集中驗證、統一的錯誤報告和恢復、資源管理以及複雜的業務邏輯編排。

🔧 配置（可選）

Docker Manager MCP 的優點之一是無需進行任何配置，它會自動發現你的 Docker 主機、設置安全連接並管理認證。但如果你需要自定義配置，可以參考以下內容：

添加自定義主機

創建 ~/.docker-mcp/config/hosts.yml 文件，示例如下：

hosts:
  # Production Docker Host
  production-server:
    hostname: 192.168.1.100
    user: myuser
    description: "Production Docker server"
    compose_path: /opt/compose       # Where to store compose files
    appdata_path: /opt/appdata       # Container data directory
    
  # Staging Docker Host  
  staging-server:
    hostname: 192.168.1.101
    user: myuser
    description: "Staging Docker server" 
    compose_path: /opt/compose       # Where to store compose files
    appdata_path: /opt/appdata       # Container data directory

使用環境變量

FASTMCP_PORT=8080                                              # Change port
LOG_LEVEL=DEBUG                                                # More verbose logging
FASTMCP_DATA_DIR=/var/lib/docker-mcp/data                     # Persist OAuth tokens & runtime data
DOCKER_MCP_DATA_DIR=/var/lib/docker-mcp/data                  # Alias for tooling expecting DOCKER_MCP_*

# OAuth Authentication (Optional but Recommended)
FASTMCP_ENABLE_OAUTH=true                                     # Enable OAuth support (defaults to off)
FASTMCP_SERVER_AUTH=fastmcp.auth.GoogleProvider               # Select Google OAuth provider
FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_ID=your-client-id           # Google OAuth client ID
FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_SECRET=your-client-secret   # Google OAuth client secret
FASTMCP_SERVER_AUTH_GOOGLE_REDIRECT_PATH=/auth/callback       # OAuth callback path
# Or use any other FastMCP auth provider by specifying its import path

🚀 傳輸方法

Rsync 傳輸特性

• 通用兼容性：適用於任何 Linux Docker 主機。
• 數據完整性：通過校驗和進行文件級驗證。
• 增量同步：使用壓縮進行增量同步，提高效率。
• 元數據保留：保留權限、時間戳和所有權。
• 可靠性：具有重試功能的逐文件傳輸。
• 適用場景：適用於所有 Docker 環境，具有通用兼容性。

性能表現

• 大型數據集：高效的增量傳輸減少帶寬使用。
• 小型堆棧：快速傳輸，開銷最小。
• 數據庫遷移：容器停止確保數據一致性。

🐳 Docker 部署

安裝程序會自動創建所有必要的文件，你可以使用以下命令進行操作：

# Check status
cd ~/.docker-mcp && docker compose ps

# View logs
cd ~/.docker-mcp && docker compose logs

# Update to latest
cd ~/.docker-mcp && docker compose pull && docker compose up -d

# Stop service
cd ~/.docker-mcp && docker compose down

🔒 內置安全機制

• 僅使用 SSH 密鑰認證：不使用密碼，提高安全性。
• 專用 SSH 密鑰：Docker Manager 使用專用的 SSH 密鑰，與個人密鑰隔離。
• 持久數據卷：使用 FASTMCP_DATA_DIR 保留 OAuth 憑證和運行時狀態，確保重啟後數據不丟失。
• OAuth 認證支持：支持 Google、GitHub 或任何 FastMCP 認證提供者。
• 身份驗證：使用 whoami 診斷工具驗證身份。
• 只讀掛載配置：確保配置文件的安全性。
• 速率限制：防止濫用。
• 非根容器執行：提高容器的安全性。
• 自動安全更新：通過 GitHub Actions 自動更新安全補丁。

OAuth 認證特性

當啟用 OAuth（設置 FASTMCP_ENABLE_OAUTH=true 並提供 FASTMCP_SERVER_AUTH）時，具有以下特性：

• 動態提供者加載 - 可以使用 Google、GitHub 或自定義認證提供者。
• whoami 工具 - 驗證認證用戶的身份和聲明。
• 安全令牌處理 - 基於 FastMCP 強大的認證框架。
• 靈活配置 - 基於環境的設置，便於部署。

💻 開發者相關

快速開發設置

git clone https://github.com/jmagar/docker-mcp
cd docker-mcp
uv sync
uv run docker-mcp

代碼格式化

uv run ruff format .
uv run ruff check . --fix

📁 項目結構

docker-mcp/
├── docker_mcp/         # Main application
│   ├── server.py       # FastMCP server with 3 consolidated tools
│   ├── core/           # Docker & SSH management
│   ├── services/       # Business logic
│   └── tools/          # Tool implementations
├── config/             # Example configurations
├── tests/              # Comprehensive test suite
└── install.sh          # One-line installer

🆘 遇到問題？

容器無法啟動

你可以向 AI 助手詢問以下問題：

"What's running on port 80 on my-server?"
"Show me the logs from my-app container on my-server"
"Why won't my nginx container start on production-1?"

無法連接到主機

讓 AI 助手幫助你進行故障排除：

"Test the connection to my staging server"
"Import all hosts from my SSH config"
"Add my new server at 192.168.1.100 to Docker Manager"

其他問題

• 查看日誌：~/.docker-mcp/data/logs/
• 開啟調試模式：LOG_LEVEL=DEBUG
• 提交問題

🎉 為何選擇 Docker Manager MCP？

• 零配置：開箱即用，無需手動配置。
• 通用控制：可以從一處管理所有 Docker 主機。
• 對 AI 友好：專為大語言模型編排基礎設施而設計。
• 生產就緒：內置速率限制、錯誤處理和日誌記錄功能。
• 默認安全：僅使用 SSH 密鑰，不使用密碼。
• 始終保持最新：通過 Docker 自動更新。

📄 許可證

本項目採用 MIT 許可證，你可以根據自己的需求自由使用。

🚀 立即開始使用

# Install in 10 seconds
curl -sSL https://raw.githubusercontent.com/jmagar/docker-mcp/main/install.sh | bash

# That's it! Start managing your Docker infrastructure

如果你有任何問題，請 提交問題，我們將竭誠為你提供幫助！