Docker Swarm MCP

🐳 Docker Swarm MCP 服务器

Docker Swarm 中缺失的 MCP 服务器。 最后，提供一个可投入生产的MCP（管理控制平面），让您能够全面掌控Docker Swarm，而无需在工具说明中迷失您的AI（此处“AI”可能指“注意力”或特指某项AI技术，根据上下文具体理解）重点。

🎯 为何存在这个

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

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

解决方案： 这台服务器通过以下方式填补了这一空白：

• ✅ 全面支持Docker Swarm - 服务、堆栈、配置、密钥
• ✅ 表示“正确”或“确认”。 智能上下文保存 - 仅显示您需要的工具（2-6个，而非23个）
• ✅ 生产安全 - 持有者令牌、TLS、远程Docker支持， *Tailscale 集成（即将推出）*
• ✅（这个符号在中文中通常表示“正确”、“确认”或“完成”的意思，但直接翻译时可能无法找到完全对应的中文词汇，因此保留原符号或根据上下文解释其含义。） 不臃肿 - 恰当的任务，恰当的时机，恰当的工具，按需筛选。

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

• 不要直接提交敏感信息。请使用环境变量（例如，MCP_ACCESS_TOKEN）、Docker 密钥或秘密管理工具。
• \.kilocode/\ 目录被 Git 忽略。如果您需要本地 MCP 客户端配置，请将 \mcp.client.json.example\ 复制到您的本地工具中，并将 \Authorization\ 设置为使用运行时值，例如 Bearer ${MCP_ACCESS_TOKEN}。

🚀 快速入门（2分钟）

1️⃣ 部署到您的Swarm集群

# Save this as docker-swarm-mcp.yml (or use one of the examples below)
# Deploy to your swarm
docker stack deploy -c docker-swarm-mcp.yml mcp-server

# Verify it's running
docker service logs mcp-server_docker-mcp

📝 Basic Stack Configuration

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  # Needs Docker socket access
    networks:
      - mcp-network

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

🔒 Production Stack with Secrets

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  # Create with: echo "your-secure-token" | docker secret create mcp_token -

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

首先设置秘密：

# Generate a secure token
openssl rand -base64 32 | docker secret create mcp_token -

# Or use your own token
echo "your-secure-token-here" | docker secret create mcp_token -

🌐 Stack with Traefik Integration

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  # High availability
      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

🔧 Multi-Node Swarm with Constraints

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  # Use host mode for better performance
    deploy:
      replicas: 1
      restart_policy:
        condition: any
        delay: 5s
      placement:
        constraints:
          - node.role == manager
          - node.labels.mcp == true  # Only on labeled nodes
        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  # Optional: Custom tool filtering

secrets:
  mcp_token:
    external: true

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

为您的节点打标签：

docker node update --label-add mcp=true 

2. 配置您的AI助手

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

记得更换 `` 使用你实际的令牌。

______________________________________________________________________

Group A: Clients with Standard Header Support

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

示例客户： Claude Desktop • Copilot 代码助手 • Gemini 命令行界面 • Visual Studio 2022 • Crush（注：此处“Crush”可能为特定应用或功能的名称，根据上下文无法确定具体含义，故直接音译）• Opencode（开源代码平台或工具）

配置：

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

⚠️ 安全提示查询参数认证（?accessToken=...出于安全原因，已在v0.5.0版本中移除了该功能。令牌绝不应出现在URL中，因为它们最终会出现在服务器日志、浏览器历史记录和引用页头中。请改用头信息。

Group B: Clients with Custom Header Support [Cursor, VS Code, etc.]

这些客户端支持自定义头部，但可能不支持全部功能 Authorization: Bearer 格式。使用 X-Access-Token 在保持URL中不包含令牌的同时，使用头部简化配置。

• 示例客户端： 光标 • VS 代码（Visual Studio Code）• Rovo 开发命令行界面（CLI）• Qodo 生成器（或Qodo Gen，根据上下文可能有所不同）• Trae

配置：

*注：键名可能是 url 或者 serverUrl 取决于客户。大多数客户接受 headers 自定义头部模块——如果某个不工作，请查阅您的客户端文档。*

*使用示例 url：*

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

*为像……这样的客户提供的示例 风帆冲浪 使用（that）的 serverUrl：*

{
  "mcpServers": {
    "docker-swarm-mcp": {
      "serverUrl": "http://localhost:8000/mcp/",
      "headers": {
        "X-Access-Token": ""
      }
    }
  }
}

Group C: Command-Line Installation The following clients support a streamlined mcp add command, allowing you to register the HTTP server directly from your terminal. 🚀

______________________________________________________________________

克劳德·科德

claude mcp add --transport http docker-swarm-mcp \
  --header "X-Access-Token: " \
  http://localhost:8000/mcp/

______________________________________________________________________

Gemini 命令行界面 (CLI)

gemini mcp add --transport http docker-swarm-mcp \
  --header "X-Access-Token: " \
  http://localhost:8000/mcp/

______________________________________________________________________

Codex CLI（注：此处“Codex”可能是一个特定项目或工具的名称，根据上下文可能有不同的翻译，但在此直接保留原样；“CLI”代表“Command Line Interface”，即“命令行界面”）

codex mcp add --transport http docker-swarm-mcp \
  --header "X-Access-Token: " \
  http://localhost:8000/mcp/

______________________________________________________________________

开源代码

opencode mcp add --transport http docker-swarm-mcp \
  --header "X-Access-Token: " \
  http://localhost:8000/mcp/

______________________________________________________________________

Qwen 代码

qwen mcp add docker-swarm-mcp \
  --header "X-Access-Token: " \
  http://localhost:8000/mcp/

注： 记得更换 ` 使用您的实际访问令牌。如果您的命令行界面（CLI）不支持自定义头部，请使用 --header "Authorization: Bearer "` 相反。

重要提示： 上述例子表明 docker-swarm-mcp 正在内部添加的对象 mcpServers 模块。您的客户端配置文件可能使用了不同的顶级键（例如。， mcp， servers)。 请将此配置合并到您现有的设置文件结构中。

3️⃣ 开始使用它吧！

只需自然地向你的AI提问：

• “哪些容器正在运行？”
• “部署我的应用栈”
• “将网络服务扩展到5个副本”
• “给我看看集群节点”

服务器会自动检测您要执行的操作，并提供恰到好处的工具！

🎯 什么让这个与众不同

🧠 智能工具过滤

传统的MCP服务器会将其所有工具都注入到您的上下文中。而这个服务器更聪明：

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

🐳 实际支持 Docker Swarm

与其他Docker MCPs不同，这个实际上理解Swarm：

• 服务 - 创建、扩展、更新、滚动部署
• 栈（Stacks） - 部署完整应用程序
• 配置与密钥 - 安全的配置管理
• 网络 - 覆盖网络，加密
• 节点 - 管理您的Swarm集群

🔒 生产安全

专为实际生产使用而打造：

• 不记名令牌认证
• Docker 密钥支持
• 到远程Docker的TLS连接
• CORS 配置
• 速率限制已就绪

📚 自我文档化

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

Ask: "How do I discover Docker tools?"
Response: Uses `discover-tools` to explain the 6 categories

💡 示例

集装箱运营

# Your AI can now:
- List all containers with detailed status
- Create containers with complex configurations
- Start/stop/restart containers
- View logs and exec into containers
- Remove containers safely

群集服务管理

# Your AI can now:
- Deploy services with replicas
- Scale services up or down
- Update services with rolling updates
- Check service logs across all replicas
- Manage service constraints and preferences

堆栈部署

# Your AI can now:
- Deploy complete application stacks
- Update stacks with new configurations
- Remove stacks cleanly
- List all stacks and their services

网络与卷管理

# Your AI can now:
- Create overlay networks for swarm
- Manage network encryption
- Create and manage volumes
- Connect/disconnect containers from networks

🛠️ 高级配置

Environment Variables

Custom Tool Filtering

编辑 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

Remote Docker Access

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：（可译为“Tailscale/WireGuard（一种网络技术或工具）”）

export DOCKER_HOST="tcp://100.x.y.z:2376"  # Tailscale IP

Building From Source

# Clone the repository
git clone https://github.com/KHAEntertainment/docker-swarm-mcp.git
cd docker-swarm-mcp

# Build with Docker
docker build -t docker-swarm-mcp:latest .

# Or build with Docker Compose
docker-compose build

# For development
poetry install
poetry run uvicorn app.main:app --reload

🧪 测试

# Quick health check
curl http://localhost:8000/mcp/health

# Test authentication (JSON-RPC)
curl -s -X POST http://localhost:8000/mcp/ \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"tools/list","params":{}}'

# Test authentication with custom header (JSON-RPC)
curl -s -X POST http://localhost:8000/mcp/ \
  -H "X-Access-Token: your-token" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"tools/list","params":{}}'

# Test with intent detection
curl -X POST http://localhost:8000/mcp/ \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "params": {"query": "show me running containers"},
    "id": 1
  }'

REST API端点现在由以下来源提供： /api/*. 设置 ENABLE_REST_API=true 在开发过程中暴露它们。

诗歌速成法

• poetry run test – 运行测试套件
• poetry run test-fast – 无覆盖（或无保障）
• poetry run test-cov – 配备覆盖率报告

📖 文档

• 客户端设置指南 - 配置Claude Desktop、Cursor等。
• 快速参考 - 常用命令
• JSON-RPC 协议 API详情
• 安全 - 最佳实践
• 路线图 - 即将推出的特性

🤝 贡献

这填补了MCP生态系统中的一个真正空白！欢迎贡献：

1. 报告错误 - 提交一个包含复现步骤的问题
2. 建议功能 - 首先查看路线图
3. 提交拉取请求（Pull Requests，简称PRs） - 遵循现有模式
4. 改进文档 - 始终感激
5. 分享你的栈（或堆叠） - 添加示例以帮助他人

关注领域：

• 更多针对Swarm的特定工具
• 更好的Portainer BE/EE集成
• 增强的安全功能
• 多集群支持

🙏 致谢

• 基于Anthropic的Model Context Protocol（MCP）和FastAPI MCP构建。
• 受在AI工作流程中对Docker Swarm适当支持的需求启发
• 得益于Docker和Swarm社区

______________________________________________________________________

许可证： 麻省理工学院 | 状态： 生产就绪 | 填补的空白： ✅

*最后，终于有一个真正理解Docker Swarm的MCP服务器。* 有关Tailscale的详细设置，请参阅docs/dependencies/tailscale.md文档。

🚀 Docker Swarm MCP 服务器 v0.5.0 - 准生产就绪

构建状态2025年10月12日，星期日，太平洋夏令时间22:19:46 已应用所有CodeRabbit修复程序 ✅