Skip to content

StackWiz MCP Installation Guide

This guide covers the complete installation and setup process for StackWiz MCP.

System Requirements

Minimum Requirements

  • OS: Linux (Ubuntu 20.04+, Debian 11+, or similar)
  • Python: 3.8 or higher
  • Docker: 20.10 or higher
  • Docker Compose: 2.0 or higher
  • Memory: 512MB available RAM
  • Storage: 100MB for StackWiz + space for Docker images

Required Software

# Check Python version
python3 --version  # Should be 3.8+

# Check Docker
docker --version
docker compose version

# Check pip
pip3 --version

Required Permissions

  • User must be in the docker group
  • Read/write access to /srv/dockerdata
  • Ability to install Python packages

Installation Methods

# Navigate to StackWiz directory
cd /srv/dockerdata/stackwiz-mcp

# Create virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate

# Install in development mode
pip install -e .

# Verify installation
python -m stackwiz_mcp --version

Method 2: System-wide Installation

cd /srv/dockerdata/stackwiz-mcp

# Install globally (requires sudo)
sudo pip install .

# Verify installation
stackwiz-mcp --version

Method 3: Docker Container

cd /srv/dockerdata/stackwiz-mcp

# Build the Docker image
docker compose build

# Run as a service
docker compose up -d

# Check logs
docker compose logs -f

Configuration

Environment Variables

Create a .env file in the StackWiz directory:

# Core Settings
STACKWIZ_BASE_DIR=/srv/dockerdata
STACKWIZ_LOG_LEVEL=INFO
STACKWIZ_ENV=production

# Docker Settings
DOCKER_HOST=unix:///var/run/docker.sock
COMPOSE_TIMEOUT=30

# DNS Settings (for Cloudflare integration)
CF_API_EMAIL=[email protected]
CF_DNS_API_TOKEN=your-cloudflare-api-token

# File Permissions
DEFAULT_USER=1000
DEFAULT_GROUP=docker

# Optional Settings
STACKWIZ_PORT=8765
STACKWIZ_METRICS_ENABLED=true

Configuration File

Create config.json for advanced settings:

{
  "server": {
    "host": "127.0.0.1",
    "port": 8765,
    "workers": 1
  },
  "docker": {
    "network": "traefik_proxy",
    "compose_version": "3.8",
    "default_restart_policy": "unless-stopped"
  },
  "dns": {
    "provider": "cloudflare",
    "default_ttl": 300,
    "proxied": true,
    "auto_create": true
  },
  "traefik": {
    "enable": true,
    "network": "traefik_proxy",
    "entrypoint": "websecure",
    "certresolver": "cf",
    "middleware": ["default-headers", "gzip"]
  },
  "templates": {
    "use_custom": false,
    "custom_path": "/srv/dockerdata/_templates"
  },
  "security": {
    "validate_images": true,
    "allowed_registries": ["docker.io", "ghcr.io"],
    "enforce_permissions": true
  }
}

Claude Desktop Integration

macOS

  1. Locate Claude configuration: 

    cd ~/Library/Application\ Support/Claude/

  2. Edit or create claude_desktop_config.json: 

    {
  "mcpServers": {
    "stackwiz": {
      "command": "python",
      "args": ["-m", "stackwiz_mcp"],
      "env": {
        "STACKWIZ_BASE_DIR": "/srv/dockerdata",
        "STACKWIZ_LOG_LEVEL": "INFO",
        "CF_API_EMAIL": "[email protected]",
        "CF_DNS_API_TOKEN": "your-token"
      }
    }
  }
}

  3. Restart Claude Desktop

Linux

  1. Configuration location varies by distribution: 

    # Common locations
~/.config/claude/claude_desktop_config.json
~/.local/share/claude/claude_desktop_config.json

  2. Use the same configuration format as macOS

Windows

  1. Configuration location: 

    %APPDATA%\Claude\claude_desktop_config.json

  2. Adjust paths for Windows: 

    {
  "mcpServers": {
    "stackwiz": {
      "command": "python",
      "args": ["-m", "stackwiz_mcp"],
      "env": {
        "STACKWIZ_BASE_DIR": "C:\\docker\\data",
        "STACKWIZ_LOG_LEVEL": "INFO"
      }
    }
  }
}

Post-Installation Setup

1. Verify Docker Access

# Test Docker access
docker ps

# If permission denied, add user to docker group
sudo usermod -aG docker $USER
# Log out and back in for changes to take effect

2. Test StackWiz Tools

# Run test suite
cd /srv/dockerdata/stackwiz-mcp
./run_tests.sh

# Manual test
python test_server.py

3. Set Up Cloudflare (Optional)

For DNS automation, you need a Cloudflare API token:

  1. Log in to Cloudflare Dashboard
  2. Go to My Profile → API Tokens
  3. Create Token with these permissions:
  4. Zone:DNS:Edit
  5. Zone:Zone:Read
  6. Add token to environment or config

4. Configure Logging

Create logging configuration:

mkdir -p ~/.cache/stackwiz-mcp/logs

# Set log rotation (optional)
cat > ~/.cache/stackwiz-mcp/logging.conf << EOF
[loggers]
keys=root,stackwiz

[handlers]
keys=console,file

[formatters]
keys=standard

[logger_root]
level=INFO
handlers=console

[logger_stackwiz]
level=DEBUG
handlers=console,file
qualname=stackwiz_mcp
propagate=0

[handler_console]
class=StreamHandler
level=INFO
formatter=standard
args=(sys.stdout,)

[handler_file]
class=handlers.RotatingFileHandler
level=DEBUG
formatter=standard
args=('~/.cache/stackwiz-mcp/logs/stackwiz.log', 'a', 10485760, 5)

[formatter_standard]
format=%(asctime)s - %(name)s - %(levelname)s - %(message)s
EOF

Verification

1. Check Server Status

# Start server manually
python -m stackwiz_mcp

# You should see:
# INFO:     Started server process
# INFO:     Waiting for application startup
# INFO:     Application startup complete

2. Test with Claude

Ask Claude:

"Can you check if StackWiz MCP is working?"

Claude should be able to: - List available tools - Show server information - Confirm connection status

3. Test Stack Creation

Ask Claude:

"Create a test stack called 'hello-world' using nginx"

This will verify: - File system access - Docker operations - Template generation

Troubleshooting Installation

Python Issues

# Wrong Python version
# Solution: Use pyenv or update system Python
pyenv install 3.11.0
pyenv local 3.11.0

# Missing pip
# Solution: Install pip
sudo apt-get install python3-pip  # Ubuntu/Debian

Docker Issues

# Docker not found
# Solution: Install Docker
curl -fsSL https://get.docker.com | sh

# Permission denied
# Solution: Add to docker group
sudo usermod -aG docker $USER
newgrp docker

MCP Connection Issues

# Check if server is running
ps aux | grep stackwiz_mcp

# Check logs
tail -f ~/.cache/stackwiz-mcp/logs/server.log

# Test connection manually
curl http://localhost:8765/health

Updating StackWiz MCP

cd /srv/dockerdata/stackwiz-mcp

# Pull latest changes
git pull

# Update dependencies
pip install -e . --upgrade

# Restart Claude Desktop to reload

Uninstallation

# Remove pip installation
pip uninstall stackwiz-mcp

# Remove configuration
rm ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Remove logs and cache
rm -rf ~/.cache/stackwiz-mcp

# Remove Docker image (if used)
docker compose down
docker rmi stackwiz-mcp:latest

Next Steps