Docker-MCP

Name: Docker-MCP
Author: jmagar

作者：jmagar2 星标更新：2025-09-27

安装使用来源：spider==github.com

项目介绍

Docker Manager MCP

从一个地方控制所有的Docker主机。 Docker Manager MCP让AI助手管理容器，部署堆栈，并监控整个基础设施的服务——无需任何配置。

🚀 一键安装

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

就这样！安装程序：

✅ 自动设置SSH密钥
✅ 从SSH配置导入所有现有主机
✅ 配置安全认证
✅ 在8000端口启动服务

无需手动配置。 如果你能通过SSH连接到它，Docker Manager就能控制它。

🎯 实际可以做什么

跨多个Docker主机部署应用程序
使用启动/停止/重启操作控制容器
实时日志流监控服务
使用Docker Compose配置管理堆栈
使用滚动更新在不停机的情况下更新服务
检查端口使用情况以避免冲突
自动发现来自SSH配置的主机

🛠 三个工具

只需用简单的英语与你的AI助手交流。 不需要复杂的命令或JSON——只需描述你想对Docker基础设施做什么。

工具1：`docker_hosts`

简化Docker主机管理工具。

操作： • list: 列出所有已配置的Docker主机

必需参数：无

• add: 添加新的Docker主机（自动运行测试连接和发现）

必需参数：host_id, ssh_host, ssh_user
可选参数：ssh_port（默认：22），ssh_key_path，description，tags，enabled（默认：true）

• ports: 列出或检查主机上的端口使用情况

必需参数：host_id
可选参数：port（用于可用性检查）

• import_ssh: 从SSH配置导入主机（自动运行测试连接和发现）

必需参数：无
可选参数：ssh_config_path，selected_hosts

• cleanup: Docker系统清理操作

必需参数：host_id, cleanup_type
合法的cleanup_type： "check" | "safe" | "moderate" | "aggressive"

• test_connection: 测试主机连通性（也运行发现）

必需参数：host_id

• discover: 发现主机上的路径和能力

必需参数：host_id（使用'all'来顺序发现所有主机）
发现：compose_path, appdata_path
单个主机：快速发现（5-15秒）
所有主机：顺序发现（总计30-60秒）

• edit: 修改主机配置

必需参数：host_id
可选参数：ssh_host, ssh_user, ssh_port, ssh_key_path, description, tags, compose_path, appdata_path, enabled

• remove: 从配置中移除主机

必需参数：host_id

• disk_usage: 只读Docker磁盘使用概要（cleanup check的别名）

必需参数：host_id

自然语言示例：

"添加一个新的名为production-1的Docker主机，地址为192.168.1.100，用户为dockeruser"
"使用SSH密钥~/.ssh/staging_key添加名为staging的主机，地址为10.0.1.50"
"列出我所有的Docker主机"
"检查production-1上正在使用的端口"
"从我的SSH配置导入主机"
"使用安全模式清理production-1上的Docker"
"测试到staging-server的连接"
"发现所有主机的能力"
"将production-1的compose路径更新为/opt/stacks"
"从我的配置中移除old-server主机"

工具2：`docker_container`

综合Docker容器管理工具。

操作： • list: 列出主机上的容器

必需参数：host_id
可选参数：all_containers, limit, offset

• info: 获取容器信息

必需参数：host_id, container_id

• start: 启动容器

必需参数：host_id, container_id
可选参数：force, timeout

• stop: 停止容器

必需参数：host_id, container_id
可选参数：force, timeout

• restart: 重启容器

必需参数：host_id, container_id
可选参数：force, timeout

• remove: 移除容器

必需参数：host_id, container_id
可选参数：force

• logs: 获取容器日志

必需参数：host_id, container_id
可选参数：follow, lines

• pull: 将容器镜像拉取到主机

必需参数：host_id, image_name

自然语言示例：

"列出production-1上的所有容器"
"包括staging上的已停止容器"
"显示production-1上nginx容器的信息"
"启动production-1上的wordpress容器"
"强制停止staging上的mysql数据库，超时时间为30秒"
"重启production-1上的web服务器容器"
"从staging移除旧缓存容器"
"获取production-1上api-server最后200行日志"
"拉取production-1上的最新nginx镜像"

工具3：`docker_compose`

综合Docker Compose堆栈管理工具。

操作： • list: 列出主机上的堆栈

必需参数：host_id

• view: 查看堆栈的compose文件

必需参数：host_id, stack_name

• deploy: 部署堆栈

必需参数：host_id, stack_name, compose_content
可选参数：environment, pull_images, recreate

• up/down/restart/build/pull: 管理堆栈生命周期

必需参数：host_id, stack_name
可选参数：options

• ps: 显示堆栈服务（状态和端口）

必需参数：host_id, stack_name

• discover: 发现主机上的compose路径

必需参数：host_id

• logs: 获取堆栈日志

必需参数：host_id, stack_name
可选参数：follow, lines, services（子集）

• migrate: 在主机之间迁移堆栈

必需参数：host_id, target_host_id, stack_name
可选参数：remove_source, skip_stop_source, start_target, dry_run

自然语言示例：

"列出production-1上的所有堆栈"
"使用这个compose文件部署wordpress堆栈到production-1：<内容>"
"将plex部署到media-server，DB_PASSWORD=secret123"
"启动production-1上的wordpress堆栈"
"关闭staging上的old-app堆栈"
"重启media-server上的plex堆栈"
"构建staging上的开发堆栈"
"发现production-1上的compose文件"
"显示production-1上wordpress堆栈的日志"
"实时流媒体media-server上plex堆栈的日志"
"显示staging上api-stack最后200行日志"
"将wordpress从old-server迁移到new-server"
"执行server1到server2的plex干跑迁移"
"迁移数据库堆栈并在源处删除"

🏗 架构：为什么是三个综合工具？

Docker Manager MCP使用综合动作-参数模式而不是27个独立工具。这种架构选择提供了：

令牌效率

2.6倍更高效：我们的3个工具使用约5k令牌，而27个独立工具使用约9.7k令牌
更好的扩展性：向现有工具添加新动作比创建新工具更有效率
上下文节省：每个工具增加约400-500令牌——综合减少这种乘法效应

复杂操作支持

Docker管理需要复杂的多步骤操作：

迁移：停止→验证→归档→传输→部署→验证
清理：分析→确认→执行→验证
部署：验证→拉取→配置→启动→健康检查

混合连接模型

不同的操作需要不同的方法：

容器操作：Docker上下文（通过SSH隧道的API）以提高效率
堆栈操作：直接SSH（文件系统访问）以管理compose文件

服务层优势

集中验证：所有操作的一致输入验证
错误处理：统一的错误报告和恢复
资源管理：连接池、上下文缓存和清理
业务逻辑：简单装饰器无法处理的复杂编排

更多技术细节，请参阅docs/consolidated-action-pattern.md

🚀 高级迁移特性：

传输方法：

Rsync：适用于所有Docker环境的通用兼容性，具有压缩和增量传输

增强的安全特性：

默认情况下总是停止容器（必须显式跳过skip_stop_source: true——不推荐）
在归档之前验证所有容器完全停止（防止数据损坏）
归档完整性验证在传输之前
文件系统同步延迟在容器关闭后
可靠的传输使用rsync保证数据一致性

💡 现实世界用例

部署WordPress站点

# WordPress部署的compose_content
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堆栈部署到production-1，使用此compose文件"

监控多个主机

只需询问你的AI助手：

"给我看看我所有的Docker主机"
"列出每个主机上的所有容器"
"给我看看production-1上nginx的日志"
"实时流媒体我所有数据库容器的日志"

应急容器管理

当出现问题时，只需描述问题：

"强制停止production-1上的所有容器"
"我的staging服务器上哪个进程占用了80端口？"
"重启我所有的web服务"
"显示production-1上当前正在运行的内容"

迁移堆栈到新主机

完美适用于硬件升级、负载均衡或迁移到更快的存储：

测试迁移（干跑）：

"执行wordpress从old-server到new-server的干跑迁移"

Rsync迁移（通用兼容性）：
- 默认情况下总是停止容器（安全第一！）
- 在归档之前验证所有容器完全停止（防止数据损坏）
- 等待文件系统同步以确保数据一致性
- 归档所有卷和数据（排除缓存、日志、node_modules）
- 在传输之前验证归档完整性
- 使用rsync进行传输并压缩
- 更新目标主机的路径
- 在目标主机上部署并启动
- 保留所有数据和配置

迁移智能处理：

命名的Docker卷和绑定挂载
Compose配置和环境变量
不同主机结构之间的路径转换
Rsync传输具有压缩和增量同步
数据一致性通过容器停止和验证

🔧 配置（可选！）

Docker Manager MCP的魅力在于你不需要配置任何东西。它会自动：

从SSH配置发现你的Docker主机
设置安全连接
管理身份验证

但如果你想自定义：

添加自定义主机

创建~/.docker-mcp/config/hosts.yml：

hosts:
  # 生产Docker主机
  production-server:
    hostname: 192.168.1.100
    user: myuser
    description: "生产Docker服务器"
    compose_path: /opt/compose       # 存储compose文件的位置
    appdata_path: /opt/appdata       # 容器数据目录
    
  # 预发布Docker主机  
  staging-server:
    hostname: 192.168.1.101
    user: myuser
    description: "预发布Docker服务器" 
    compose_path: /opt/compose       # 存储compose文件的位置
    appdata_path: /opt/appdata       # 容器数据目录

使用环境变量

FASTMCP_PORT=8080                                              # 更改端口
LOG_LEVEL=DEBUG                                                # 更详细的日志记录
FASTMCP_DATA_DIR=/var/lib/docker-mcp/data                     # 持久化OAuth令牌及运行时数据
DOCKER_MCP_DATA_DIR=/var/lib/docker-mcp/data                  # 工具期望的DOCKER_MCP_*别名

# OAuth身份验证（可选但推荐）
FASTMCP_ENABLE_OAUTH=true                                     # 启用OAuth支持（默认关闭）
FASTMCP_SERVER_AUTH=fastmcp.auth.GoogleProvider               # 选择Google OAuth提供者
FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_ID=your-client-id           # Google OAuth客户端ID
FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_SECRET=your-client-secret   # Google OAuth客户端密钥
FASTMCP_SERVER_AUTH_GOOGLE_REDIRECT_PATH=/auth/callback       # OAuth回调路径
# 或通过指定其导入路径使用任何其他FastMCP身份验证提供者

🚀 传输方法

Rsync传输特性：

通用兼容性：适用于任何Linux Docker主机
数据完整性：基于校验和的文件级验证
增量：压缩增量同步以提高效率
元数据：保留权限、时间戳和所有权
可靠：逐文件传输并具备重试能力
应用场景：所有Docker环境，通用兼容性

性能：

大数据集：高效的增量传输减少带宽
小型堆栈：快速传输且开销最小
数据库迁移：容器停止确保数据一致性

🐳 Docker部署

已经包含！安装程序创建一切：

# 检查状态
cd ~/.docker-mcp && docker compose ps

# 查看日志
cd ~/.docker-mcp && docker compose logs

# 更新到最新
cd ~/.docker-mcp && docker compose pull && docker compose up -d

# 停止服务
cd ~/.docker-mcp && docker compose down

🔒 内置安全

仅SSH密钥认证（无密码）
专用SSH密钥用于Docker Manager（与个人密钥隔离）
持久数据卷（FASTMCP_DATA_DIR）在重启之间保留OAuth凭据和运行时状态
OAuth身份验证支持（Google、GitHub或任何FastMCP提供者）
身份验证使用whoami诊断工具
只读挂载用于配置
速率限制防止滥用
非root容器执行
自动安全更新通过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/         # 主应用程序
│   ├── server.py       # 包含3个综合工具的FastMCP服务器
│   ├── core/           # Docker & SSH管理
│   ├── services/       # 业务逻辑
│   └── tools/          # 工具实现
├── config/             # 示例配置
├── tests/              # 综合测试套件
└── install.sh          # 一键安装器

🆘 需要帮助？

容器无法启动？

只需询问你的AI助手：

"我的my-server上80端口正在运行什么？"
"显示my-server上my-app容器的日志"
"为什么production-1上的nginx容器无法启动？"

无法连接到主机？

让您的AI助手帮助排查：

"测试到我的预发布服务器的连接"
"从我的SSH配置导入所有主机"
"将我的新服务器192.1

Docker-MCP

项目介绍

Docker Manager MCP

🚀 一键安装

🎯 实际可以做什么

🛠 三个工具

工具1：docker_hosts

工具2：docker_container

工具3：docker_compose

🏗 架构：为什么是三个综合工具？

令牌效率

复杂操作支持

混合连接模型

服务层优势

💡 现实世界用例

部署WordPress站点

监控多个主机

应急容器管理

迁移堆栈到新主机

🔧 配置（可选！）

添加自定义主机

使用环境变量

🚀 传输方法

🐳 Docker部署

🔒 内置安全

OAuth身份验证特性

💻 开发者

快速开发设置

格式化代码

📁 内容一览

🆘 需要帮助？

容器无法启动？

无法连接到主机？

工具1：`docker_hosts`

工具2：`docker_container`

工具3：`docker_compose`