🐳 Docker Swarm MCP Server

The missing MCP server for Docker Swarm. Finally, a production-ready MCP that gives you full Docker Swarm control without drowning your AI in tool descriptions.

🎯 Why This Exists

The Gap: After searching the MCP ecosystem, I found:

❌ Regular Docker MCPs with limited functionality (containers only, localhost only)
❌ Portainer MCP that only works with CE (not BE/EE)
❌ No proper Swarm support anywhere
❌ All existing servers dump 20+ tools into your agents context window

The Solution: This server fills that gap with:

✅ Full Docker Swarm support - Services, stacks, configs, secrets
✅ Smart context preservation - Only shows tools you need (2-6 instead of 23)
✅ Production security - Bearer tokens, TLS, remote Docker support, Tailscale Integration (coming soon)
✅ No bloat - Just the tools you need, when you need them, filtered by the task at hand.

Note on secrets and client config:

Do not commit secrets. Use environment variables (e.g., MCP_ACCESS_TOKEN), Docker secrets, or a secret manager.
The .kilocode/ directory is gitignored. If you need a local MCP client config, copy mcp.client.json.example to your local tooling and set Authorization to use a runtime value like Bearer ${MCP_ACCESS_TOKEN}.

🚀 Quick Start (2 Minutes)

1️⃣ Deploy to Your 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

Setup the secret first:

# 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

Label your node:

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

2. Configure Your AI Assistant

Different AI assistants and code editors configure MCP servers in slightly different ways. Find your client in the groups below and use the corresponding JSON configuration.

Remember to replace <YOUR_SECURE_TOKEN_HERE> with your actual token.

Group A: Clients with Standard Header Support

These clients use a more structured format that supports passing the API token securely in the request headers. This is the recommended and most secure method.

Example Clients: Claude Desktop • Copilot Coding Agent • Gemini CLI • Visual Studio 2022 • Crush • Opencode

Configuration:

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

⚠️ Security Note: Query parameter authentication (?accessToken=...) has been removed in v0.5.0 for security reasons. Tokens should never appear in URLs because they end up in server logs, browser history, and referrer headers. Use headers instead.

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

These clients support custom headers but may not support the full Authorization: Bearer format. Use the X-Access-Token header for simpler configuration while keeping tokens out of the URL.

Example Clients: Cursor • VS Code • Rovo Dev CLI • Qodo Gen • Trae

Configuration:

Note: The key name might be url or serverUrl depending on the client. Most clients accept a headers block for custom headers—check your client's documentation if one doesn't work.

Example using url:

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

Example for clients like Windsurf that use serverUrl:

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

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 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/

Note: Remember to replace <your-secure-token-here> with your actual access token. If your CLI does not support custom headers, use --header "Authorization: Bearer <your-secure-token-here>" instead.

-----

Important Note: The examples above show the docker-swarm-mcp object being added inside an mcpServers block. Your client's configuration file might use a different top-level key (e.g., mcp, servers). Please merge this configuration into your existing settings file structure.

3️⃣ Start Using It!

Just ask your AI naturally:

"What containers are running?"
"Deploy my app stack"
"Scale the web service to 5 replicas"
"Show me the swarm nodes"

The server automatically detects what you're trying to do and provides just the right tools!

🎯 What Makes This Different

🧠 Smart Tool Filtering

Traditional MCP servers dump all their tools into your context. This server is smarter:

You Say	Tools Returned	Context Saved
"List my containers"	4 container tools	19 tools hidden
"Deploy a stack"	3 compose tools	20 tools hidden
"Check swarm status"	3 swarm tools	20 tools hidden
"Create a network"	3 network tools	20 tools hidden

Your AI focuses on YOUR project, not on reading documentation.

🐳 Real Docker Swarm Support

Unlike other Docker MCPs, this one actually understands Swarm:

Services - Create, scale, update, rolling deployments
Stacks - Deploy complete applications
Configs & Secrets - Secure configuration management
Networks - Overlay networks, encryption
Nodes - Manage your swarm cluster

🔒 Production Security

Built for real production use:

Bearer token authentication
Docker secrets support
TLS connections to remote Docker
CORS configuration
Rate limiting ready

📚 Self-Documenting

Your AI can learn the system through meta-tools:

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

💡 Examples

Container Operations

# 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

Swarm Service Management

# 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

Stack Deployments

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

Network & Volume Management

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

🛠️ Advanced Configuration

Environment Variables

Variable	Required	Default	Description
`MCP_ACCESS_TOKEN`	✅	-	Bearer token for authentication
`DOCKER_HOST`	❌	`unix:///var/run/docker.sock`	Docker engine connection
`DOCKER_TLS_VERIFY`	❌	`0`	Enable TLS verification (1/0)
`DOCKER_CERT_PATH`	❌	-	Path to TLS certificates
`LOG_LEVEL`	❌	`INFO`	DEBUG shows context metrics
`ALLOWED_ORIGINS`	❌	`*`	CORS origins (comma-separated)
`MCP_TRANSPORT`	❌	`http`	Transport mode (http/sse)

Custom Tool Filtering

Edit filter-config.json to customize which tools are available:

{
  "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"]
}

Mount as a config in your stack:

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

services:
  docker-mcp:
    configs:
      - source: filter_config
        target: /app/filter-config.json

Remote Docker Access

TLS Connection:

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

SSH Connection:

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

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

🧪 Testing

# 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 endpoints are now served from /api/*. Set ENABLE_REST_API=true to expose them during development.

Poetry Shortcuts

poetry run test – run test suite
poetry run test-fast – no coverage
poetry run test-cov – with coverage reports

📖 Documentation

Client Setup Guide - Configure Claude Desktop, Cursor, etc.
Quick Reference - Common commands
JSON-RPC Protocol - API details
Security - Best practices
Roadmap - Coming features

🤝 Contributing

This fills a real gap in the MCP ecosystem! Contributions welcome:

Report bugs - Open an issue with reproduction steps
Suggest features - Check the roadmap first
Submit PRs - Follow existing patterns
Improve docs - Always appreciated
Share your stacks - Add examples to help others

Focus areas:

More Swarm-specific tools
Better Portainer BE/EE integration
Enhanced security features
Multi-cluster support

🙏 Acknowledgments

Built on the Model Context Protocol (MCP) by Anthropic with FastAPI MCP.
Inspired by the need for proper Docker Swarm support in AI workflows
Thanks to the Docker and Swarm communities

License: MIT | Status: Production Ready | Gap Filled: ✅

Finally, an MCP server that actually understands Docker Swarm. See docs/dependencies/tailscale.md for detailed Tailscale setup.

🚀 Docker Swarm MCP Server v0.5.0 - Production Ready

Build Status: Sun Oct 12 22:19:46 PDT 2025 All CodeRabbit fixes applied ✅

docker-swarm-mcp