🐳 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

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 `` with your actual token.

---

⚠️ 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.

---

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:

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

🧪 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:

1. Report bugs - Open an issue with reproduction steps
2. Suggest features - Check the roadmap first
3. Submit PRs - Follow existing patterns
4. Improve docs - Always appreciated
5. 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 ✅