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

如果你有任何问题，请 提交问题，我们将竭诚为你提供帮助！