STARWARCLOUD STARWAR.AI
返回市场
docker集群-mcp

docker集群-mcp

作者：KHAEntertainment2 星标更新：2025-10-13
安装使用来源：spider==github.com

项目介绍

🐳 Docker Swarm MCP Server

Docker Swarm 缺失的 MCP 服务器。 终于有了一个生产就绪的 MCP，它能让你完全控制 Docker Swarm，而不会让你的AI淹没在工具描述中。

Semgrep Code Reviewed by CodeRabbit Version Production Ready

🎯 为什么存在这个项目

存在的差距： 在搜索了MCP生态系统之后，我发现：

  • ❌ 功能有限的常规Docker MCP（仅限容器，仅限本地主机）
  • ❌ 只适用于CE版本的Portainer MCP（不支持BE/EE）
  • ❌ 任何地方都没有合适的Swarm支持
  • ❌ 所有现有的服务器都会将20多个工具放入代理上下文窗口

解决方案： 这个服务器填补了这些空白：

  • ✅ 完整的Docker Swarm支持 - 服务、堆栈、配置、密钥
  • ✅ 智能上下文保留 - 只显示你需要的工具（2-6个而不是23个）
  • ✅ 生产安全性 - 带有令牌、TLS、远程Docker支持，即将集成Tailscale
  • ✅ 无冗余 - 只提供你需要的工具，按需过滤

关于密钥和客户端配置的说明：

  • 不要提交密钥。使用环境变量（例如，MCP_ACCESS_TOKEN），Docker密钥或密钥管理器。
  • .kilocode/目录被git忽略。如果你需要本地MCP客户端配置，请复制mcp.client.json.example到你的本地工具，并设置授权以使用运行时值如Bearer ${MCP_ACCESS_TOKEN}。

🚀 快速开始（2分钟）

1️⃣ 部署到你的Swarm

# 将此保存为docker-swarm-mcp.yml（或使用下面的示例之一）
# 部署到你的Swarm
docker stack deploy -c docker-swarm-mcp.yml mcp-server

# 验证是否正在运行
docker service logs mcp-server_docker-mcp
<details> <summary><b>📝 基本堆栈配置</b></summary> 
version: '3.8'

services:
  docker-mcp:
    image: ghcr.io/khaentertainment/docker-swarm-mcp:latest
    environment:
      - MCP_ACCESS_TOKEN=${MCP_ACCESS_TOKEN:-change-me-to-secure-token}
      - LOG_LEVEL=INFO
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - "8000:8000"
    deploy:
      replicas: 1
      restart_policy:
        condition: any
        delay: 5s
      placement:
        constraints:
          - node.role == manager  # 需要Docker套接字访问权限
    networks:
      - mcp-network

networks:
  mcp-network:
    driver: overlay
    attachable: true
</details> <details> <summary><b>🔒 生产堆栈与密钥</b></summary> 
version: '3.8'

services:
  docker-mcp:
    image: ghcr.io/khaentertainment/docker-swarm-mcp:latest
    environment:
      - MCP_ACCESS_TOKEN_FILE=/run/secrets/mcp_token
      - LOG_LEVEL=INFO
      - ALLOWED_ORIGINS=https://claude.ai,http://localhost:*
    secrets:
      - mcp_token
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - "8000:8000"
    deploy:
      replicas: 1
      restart_policy:
        condition: any
        delay: 5s
      placement:
        constraints:
          - node.role == manager
      resources:
        limits:
          memory: 512M
        reservations:
          memory: 128M
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/mcp/health"]
      interval: 30s
      timeout: 3s
      retries: 3
    networks:
      - mcp-network

secrets:
  mcp_token:
    external: true  # 创建方式：echo "your-secure-token" | docker secret create mcp_token -

networks:
  mcp-network:
    driver: overlay
    attachable: true
    encrypted: true

先设置密钥：

# 生成安全令牌
openssl rand -base64 32 | docker secret create mcp_token -

# 或者使用自己的令牌
echo "your-secure-token-here" | docker secret create mcp_token -
</details> <details> <summary><b>🌐 堆栈与Traefik集成</b></summary> 
version: '3.8'

services:
  docker-mcp:
    image: ghcr.io/khaentertainment/docker-swarm-mcp:latest
    environment:
      - MCP_ACCESS_TOKEN_FILE=/run/secrets/mcp_token
      - LOG_LEVEL=INFO
      - ALLOWED_ORIGINS=https://mcp.yourdomain.com
    secrets:
      - mcp_token
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    deploy:
      replicas: 2  # 高可用性
      restart_policy:
        condition: any
        delay: 5s
      placement:
        constraints:
          - node.role == manager
      update_config:
        parallelism: 1
        delay: 10s
      labels:
        - "traefik.enable=true"
        - "traefik.http.routers.mcp.rule=Host(`mcp.yourdomain.com`)"
        - "traefik.http.routers.mcp.entrypoints=websecure"
        - "traefik.http.routers.mcp.tls=true"
        - "traefik.http.routers.mcp.tls.certresolver=letsencrypt"
        - "traefik.http.services.mcp.loadbalancer.server.port=8000"
        - "traefik.http.middlewares.mcp-headers.headers.customrequestheaders.Authorization=Bearer ${MCP_TOKEN}"
        - "traefik.http.routers.mcp.middlewares=mcp-headers"
    networks:
      - traefik-public
      - mcp-internal

secrets:
  mcp_token:
    external: true

networks:
  traefik-public:
    external: true
  mcp-internal:
    driver: overlay
    encrypted: true
    internal: true
</details> <details> <summary><b>🔧 多节点Swarm与约束条件</b></summary> 
version: '3.8'

services:
  docker-mcp:
    image: ghcr.io/khaentertainment/docker-swarm-mcp:latest
    environment:
      - MCP_ACCESS_TOKEN_FILE=/run/secrets/mcp_token
      - LOG_LEVEL=INFO
    secrets:
      - mcp_token
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    ports:
      - target: 8000
        published: 8000
        protocol: tcp
        mode: host  # 使用host模式以获得更好的性能
    deploy:
      replicas: 1
      restart_policy:
        condition: any
        delay: 5s
      placement:
        constraints:
          - node.role == manager
          - node.labels.mcp == true  # 仅在标记的节点上
        preferences:
          - spread: node.id
      update_config:
        parallelism: 1
        delay: 10s
        failure_action: rollback
      rollback_config:
        parallelism: 1
        delay: 10s
    networks:
      - mcp-network

configs:
  filter_config:
    file: ./filter-config.json  # 可选：自定义工具过滤

secrets:
  mcp_token:
    external: true

networks:
  mcp-network:
    driver: overlay
    attachable: true
    encrypted: true

标记你的节点：

docker node update --label-add mcp=true <node-name>
</details>

2. 配置你的AI助手

不同的AI助手和代码编辑器配置MCP服务器的方式略有不同。在下面的组中找到你的客户端并使用相应的JSON配置。

记得将<YOUR_SECURE_TOKEN_HERE>替换为实际的令牌。

<details open> <summary><b>组A：支持标准头部的客户端</b></summary>

这些客户端使用更结构化的格式，支持在请求头中安全地传递API令牌。这是推荐且最安全的方法。

示例客户端： Claude Desktop   • Copilot Coding Agent   • Gemini CLI   • Visual Studio 2022   • Crush   • Opencode

配置：

{
  "mcpServers": {
    "docker-swarm-mcp": {
      "transport": {
        "type": "http",
        "url": "http://localhost:8000/mcp/",
        "headers": {
          "Authorization": "Bearer <YOUR_SECURE_TOKEN_HERE>"
        }
      }
    }
  }
}
</details>

⚠️ 安全提示：出于安全原因，v0.5.0版本已移除查询参数认证（?accessToken=...）。令牌不应出现在URL中，因为它们会出现在服务器日志、浏览器历史记录和引用头中。请使用头部。

<details> <summary><b>组B：支持自定义头部的客户端 [Cursor, VS Code等]</b></summary>

这些客户端支持自定义头部，但可能不支持完整的Authorization: Bearer格式。使用X-Access-Token头部进行简单的配置，同时将令牌保留在URL之外。

  • 示例客户端： Cursor   • VS Code • Rovo Dev CLI • Qodo Gen • Trae

配置：

注意：键名可能是url或serverUrl，取决于客户端。大多数客户端接受用于自定义头部的headers块——如果一个不起作用，请检查客户端文档。

使用url的示例：

{
  "mcpServers": {
    "docker-swarm-mcp": {
      "type": "http",
      "url": "http://localhost:8000/mcp/",
      "headers": {
        "X-Access-Token": "<YOUR_SECURE_TOKEN_HERE>"
      }
    }
  }
}

对于使用serverUrl的客户端如Windsurf：

{
  "mcpServers": {
    "docker-swarm-mcp": {
      "serverUrl": "http://localhost:8000/mcp/",
      "headers": {
        "X-Access-Token": "<YOUR_SECURE_TOKEN_HERE>"
      }
    }
  }
}
</details> <details> <summary><b>组C：命令行安装</b></summary> 以下客户端支持流线型的`mcp add`命令，允许你直接从终端注册HTTP服务器。🚀

Claude Code

claude mcp add --transport http docker-swarm-mcp \
  --header "X-Access-Token: <your-secure-token-here>" \
  http://localhost:8000/mcp/

Gemini CLI

gemini mcp add --transport http docker-swarm-mcp \
  --header "X-Access-Token: <your-secure-token-here>" \
  http://localhost:8000/mcp/

Codex CLI

codex mcp add --transport http docker-swarm-mcp \
  --header "X-Access-Token: <your-secure-token-here>" \
  http://localhost:8000/mcp/

Opencode

opencode mcp add --transport http docker-swarm-mcp \
  --header "X-Access-Token: <your-secure-token-here>" \
  http://localhost:8000/mcp/

Qwen Code

qwen mcp add docker-swarm-mcp \
  --header "X-Access-Token: <your-secure-token-here>" \
  http://localhost:8000/mcp/

注意： 记得将<your-secure-token-here>替换为实际的访问令牌。如果CLI不支持自定义头部，请使用--header "Authorization: Bearer <your-secure-token-here>"代替。

</details> -----

重要提示： 上面的例子展示了docker-swarm-mcp对象被添加到mcpServers块内。你的客户端配置文件可能使用不同的顶级键（例如，mcp，servers）。请将此配置合并到现有设置文件结构中。

3️⃣ 开始使用！

只需自然地询问你的AI：

  • "哪些容器正在运行？"
  • "部署我的应用堆栈"
  • "将web服务扩展到5个副本"
  • "显示我Swarm节点"

服务器会自动检测你想要做什么，并提供正确的工具！

🎯 这有什么不同

🧠 智能工具筛选

传统的MCP服务器会把所有工具都塞进你的上下文中。这个服务器更聪明：

你说返回的工具保留的上下文
"列出我的容器"4个容器工具隐藏19个工具
"部署一个堆栈"3个组合工具隐藏20个工具
"检查Swarm状态"3个Swarm工具隐藏20个工具
"创建网络"3个网络工具隐藏20个工具

你的AI专注于你的项目，而不是阅读文档。

🐳 真正的Docker Swarm支持

与其他Docker MCP不同，这个MCP真正理解Swarm：

  • 服务 - 创建、缩放、更新、滚动部署
  • 堆栈 - 部署完整应用程序
  • 配置和密钥 - 安全配置管理
  • 网络 - 覆盖网络、加密
  • 节点 - 管理你的Swarm集群

🔒 生产安全性

为真正的生产用途构建：

  • 带有令牌的身份验证
  • Docker密钥支持
  • 到远程Docker的TLS连接
  • CORS配置
  • 准备好速率限制

📚 自动文档

你的AI可以通过元工具学习系统：

询问："如何发现Docker工具？"
响应：使用`discover-tools`来解释6个类别

💡 示例

容器操作

# 你的AI现在可以：
- 列出所有容器及其详细状态
- 创建具有复杂配置的容器
- 启动/停止/重启容器
- 查看日志并进入容器
- 安全删除容器

Swarm服务管理

# 你的AI现在可以：
- 部署具有副本的服务
- 缩放服务
- 使用滚动更新更新服务
- 检查所有副本的服务日志
- 管理服务约束和偏好

堆栈部署

# 你的AI现在可以：
- 部署完整的应用程序堆栈
- 使用新配置更新堆栈
- 清洁地移除堆栈
- 列出所有堆栈及其服务

网络和卷管理

# 你的AI现在可以：
- 为Swarm创建覆盖网络
- 管理网络加密
- 创建和管理卷
- 将容器连接/断开网络

🛠️ 高级配置

<details> <summary><b>环境变量</b></summary>
变量必需默认值描述
MCP_ACCESS_TOKEN✅-身份验证的令牌
DOCKER_HOST❌unix:///var/run/docker.sockDocker引擎连接
DOCKER_TLS_VERIFY❌0启用TLS验证（1/0）
DOCKER_CERT_PATH❌-TLS证书路径
LOG_LEVEL❌INFODEBUG显示上下文指标
ALLOWED_ORIGINS❌*CORS来源（逗号分隔）
MCP_TRANSPORT❌http传输模式（http/sse）
</details> <details> <summary><b>自定义工具筛选</b></summary>

编辑filter-config.json来自定义可用的工具：

{
  "task_type_allowlists": {
    "container-ops": ["list-containers", "create-container", "start-container"],
    "swarm-ops": ["list-services", "create-service", "scale-service"],
    "compose-ops": ["deploy-stack", "list-stacks"]
  },
  "max_tools": 10,
  "blocklist": ["remove-volume", "prune-system"]
}

作为配置挂载到堆栈中：

configs:
  filter_config:
    file: ./filter-config.json

services:
  docker-mcp:
    configs:
      - source: filter_config
        target: /app/filter-config.json
</details> <details> <summary><b>远程Docker访问</b></summary>

TLS连接：

export DOCKER_HOST="tcp://remote-host:2376"
export DOCKER_TLS_VERIFY="1"
export DOCKER_CERT_PATH="/path/to/certs"

SSH连接：

export DOCKER_HOST="ssh://user@remote-host"

Tailscale/Wireguard：