StackWiz MCP Server

Transform your Docker infrastructure management with an AI-powered Model Context Protocol (MCP) server. StackWiz MCP enables AI assistants like Claude to create, manage, and deploy containerized services in your infrastructure programmatically.

📖 Documentation

For AI Agents: Start with CLAUDE.md, refer to docs/AGENT_REFERENCE.md for detailed tool parameters.

For DevOps/Deployment: See docs/TECHNICAL_OVERVIEW.md for architecture details and environment configuration.

Related MCP server: Docker MCP Server

🚀 Quick Start

Installation

# Install from Git (recommended)
pip install git+https://gitea.rbnk.uk/admin/stackwiz-mcp.git
# Or from GitHub:
pip install git+https://github.com/rickoslyder/stackwiz-mcp.git

# Or clone and install locally
git clone https://gitea.rbnk.uk/admin/stackwiz-mcp.git
cd stackwiz-mcp
pip install -e .

Claude Desktop Integration

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "stackwiz": {
      "command": "python",
      "args": ["-m", "stackwiz_mcp"],
      "env": {
        "STACKWIZ_BASE_DIR": "/srv/dockerdata",
        "STACKWIZ_LOG_LEVEL": "INFO"
      }
    }
  }
}

Basic Usage

Once configured, you can ask Claude to:

• "Create a new Grafana monitoring service"

• "Deploy a Pocketbase backend for my todo app"

• "List all running Docker stacks"

• "Create a PostgreSQL database with automatic backups"

• "Set up a Ghost blog with custom domain"

🎯 Features

Stack Management

• Create Stacks: Deploy any Docker container with automatic Traefik integration

• Pocketbase Support: Specialized support for Pocketbase backends

• List & Monitor: View all stacks with real-time status

• Lifecycle Control: Start, stop, restart, and remove stacks

• Log Access: Retrieve container logs for debugging

DNS Automation

• Cloudflare Integration: Full DNS record management (create, list, update, delete)

• Multiple Record Types: A, AAAA, CNAME, TXT, MX support

• Smart Defaults: Auto-detect server IP for A records

• Proxy Control: Toggle Cloudflare proxy (orange/gray cloud) per record

• Rate Limit Handling: Automatic retry with exponential backoff

• Zone ID Caching: Efficient API usage with 5-minute cache

Infrastructure Integration

• Traefik Ready: Automatic SSL/TLS with Let's Encrypt

• Network Management: Proper Docker network configuration

• Permission Handling: Secure file permissions (750/640)

• Template System: Consistent stack structure

📚 Available Tools

create_stack

Creates a new Docker service stack.

Parameters:

• name (required): Stack identifier (lowercase, alphanumeric + hyphens)

• type: "generic" or "pocketbase"

• domain: Full domain for the service

• image: Docker image (required for generic)

• port: Container port (required for generic)

• create_dns: Auto-create DNS record

• auto_start: Start immediately after creation

• environment: Additional environment variables

list_stacks

Lists all Docker stacks in the infrastructure.

Parameters:

• filter: Filter stacks by name

• include_status: Include container status

• sort_by: Sort by name, created, or status

manage_stack

Performs operations on existing stacks.

Parameters:

• stack_name (required): Target stack

• action: start, stop, restart, remove, logs

• options: Additional options (follow_logs, tail_lines)

create_dns_record

Creates DNS records in Cloudflare with automatic retry and rate limit handling.

Parameters:

• subdomain (required): Subdomain to create

• type: Record type (A, CNAME, MX, TXT)

• value: Record value (AUTO for server IP)

• proxied: Enable Cloudflare proxy

list_dns_records

Lists DNS records from Cloudflare.

Parameters:

• filter: Filter records by name (partial match)

update_dns_proxy

Toggles Cloudflare proxy for a DNS record.

Parameters:

• subdomain (required): Target subdomain

• enable (required): true for proxied, false for DNS-only

delete_dns_record

Deletes DNS records from Cloudflare.

Parameters:

• subdomain (required): Subdomain to delete

validate_stack_config

Validates configuration before creation.

Parameters:

• config (required): Stack configuration object

• check_conflicts: Check for port/domain conflicts

🗂️ Resources

The MCP server provides read access to:

• Stack Configurations: stack://list, stack://{name}/compose

• Templates: template://generic, template://pocketbase

• Infrastructure Info: infra://networks, infra://domains

💡 Prompts

Interactive deployment guides:

• deploy-web-app: Step-by-step web application deployment

• setup-database: Database deployment with best practices

• create-api-service: API service with monitoring

🏗️ Architecture

stackwiz-mcp/
├── stackwiz_mcp/          # Main package
│   ├── server.py          # FastMCP server (preferred)
│   ├── mcp_server.py      # Standard MCP implementation
│   ├── config.py          # Configuration management
│   ├── tools/             # MCP tool implementations
│   ├── resources/         # Resource providers
│   ├── prompts/          # Interactive prompts
│   ├── models/           # Pydantic models
│   └── utils/            # Utilities
├── tests/                # Test suite
├── docs/                 # Documentation
└── examples/             # Usage examples

🧪 Testing

# Run the test suite
./run_tests.sh

# Manual testing
python test_server.py

# Run specific tests
pytest tests/test_mcp_server.py -v

🐳 Docker Deployment

# Build and run with Docker
docker compose up -d

# View logs
docker compose logs -f

# Stop the server
docker compose down

⚙️ Configuration

Environment Variables

• STACKWIZ_BASE_DIR: Base directory for stacks (default: /srv/dockerdata)

• STACKWIZ_LOG_LEVEL: Logging level (DEBUG, INFO, WARNING, ERROR)

• STACKWIZ_ENV: Environment (development, production)

• DOCKER_HOST: Docker daemon socket

• CF_API_EMAIL: Cloudflare email

• CF_DNS_API_TOKEN: Cloudflare API token

• DEFAULT_USER: File owner (default: current user)

• DEFAULT_GROUP: File group (default: docker)

Configuration File

Create config.json for persistent settings:

{
  "docker": {
    "network": "traefik_proxy",
    "compose_timeout": 30
  },
  "dns": {
    "default_ttl": 300,
    "proxied": true
  },
  "traefik": {
    "entrypoint": "websecure",
    "certresolver": "cf"
  }
}

🔒 Security

• Input Validation: All inputs validated with Pydantic

• Command Injection Protection: Safe command execution

• Path Traversal Prevention: Restricted to base directory

• Secrets Management: Environment variables never logged

• Permission Management: Proper Unix permissions

🤝 Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests for new functionality

5. Run the test suite

6. Submit a pull request

📝 License

MIT License - See LICENSE file for details.

🙏 Acknowledgments

• Built on the Model Context Protocol specification

• Uses FastMCP framework

• Inspired by the original stackwiz shell script

🐛 Troubleshooting

Server won't start

• Check Python version (3.8+ required)

• Verify dependencies: pip install -r requirements.txt

• Check permissions on base directory

Tools not working

• Ensure Docker daemon is running

• Verify user is in docker group

• Check DOCKER_HOST environment variable

DNS creation fails

• Verify Cloudflare API credentials (CF_API_TOKEN or CF_DNS_API_TOKEN)

• Check domain is managed by Cloudflare

• Ensure API token has DNS edit permissions

• Rate limits are handled automatically with retries

• See logs for detailed error messages

DNS proxy toggle fails

• Only A, AAAA, and CNAME records can be proxied

• MX and TXT records cannot be proxied (Cloudflare limitation)

Logs location

• Server logs: ~/.cache/stackwiz-mcp/logs/

• Stack logs: docker compose -f {stack}/docker-compose.yml logs

📞 Support

• GitHub Issues: Report bugs and feature requests

• Documentation: See /docs directory

• Examples: Check /examples for usage patterns