docker-swarm

The Docker Swarm MCP Server provides full Docker Swarm control through the MCP framework. It exposes tools to manage Swarm entities such as services, stacks, configs, and secrets, while preserving context so your AI assistants only see the tools relevant to the current task. You can run the server in Docker and then configure your MCP client to talk to the HTTP API exposed by the container at port 8000 by default. To secure access, you use a bearer token (MCP_ACCESS_TOKEN) that must be provided in your client configuration as an Authorization header. The server supports remote Docker endpoints, TLS, and can be integrated behind reverse proxies or Traefik as shown in the examples, enabling production-grade deployments with token-based access control.

To use the MCP with your AI assistant or editor, set up an MCP client configuration that points to http://<host>:8000/mcp/ and include the Authorization header with your Bearer token. The recommended configuration uses standard headers for authentication to avoid token exposure in URLs. Example client configuration maps the docker-swarm-mcp server to the MCP HTTP API and passes your token securely in the header. Once configured, you can issue standard MCP commands to manage Swarm components such as creating and updating services, deploying stacks, or managing configs and secrets, all through the MCP interface supported by the server.

Prerequisites:

• Docker installed on a host that can access a Docker daemon (for Swarm management, usually a manager node).
• A secure token to authorize MCP API requests (generate and keep secret).

1. Prepare your environment

• Initialize or join a Docker Swarm if not already done.
• Ensure port 8000 is accessible for the MCP API, or adjust as needed in deployment.

2. Pull and run the MCP container

• Example using Docker run:

export MCP_TOKEN=<your-secure-token-here>

docker run -d --name docker-swarm-mcp \
  -e MCP_ACCESS_TOKEN="$MCP_TOKEN" \
  -e LOG_LEVEL=INFO \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -p 8000:8000 \
  ghcr.io/khaentertainment/docker-swarm-mcp:latest

3. Verify the MCP is reachable

• Check logs and health endpoint (if configured) to confirm the server is up.
• Access the API at http://<host>:8000/mcp/ to list available tools and ensure authentication works.

4. Optional: secure with TLS or reverse proxy

• Deploy behind Traefik or another proxy and terminate TLS at the edge.
• Use a secret-based token (MCP_ACCESS_TOKEN) and secrets management for production.

5. Client configuration

• Configure your MCP client (AI agent, editor, or code host) to use the server URL and pass the Bearer token in the Authorization header, as recommended in the docs.

Tips and notes:

• Do not commit MCP tokens or secrets in code; use environment variables or Docker secrets where possible.
• If exposing the API publicly, enforce TLS and strict firewall rules to protect the token.
• The server supports remote Docker endpoints; ensure the remote Docker daemon is securely exposed (TLS, certs) if used.
• When running in Swarm, consider using secrets for MCP_TOKEN and enable healthchecks to monitor service health.
• If you are integrating behind Traefik, you can leverage the provided examples to configure TLS, routes, and headers. Always pass the token via the Authorization header, not in query parameters or path segments.
• For troubleshooting, verify that the container has access to /var/run/docker.sock and that the host exposes port 8000 (or the port you configure).
• If you update the image, redeploy the container with the new image tag and ensure the same environment and volume mappings are preserved.