Skip to content

StackWiz MCP Documentation

Overview

StackWiz MCP (Model Context Protocol) is an AI-powered server that enables AI assistants like Claude to programmatically create, manage, and deploy Docker-based services in your infrastructure. It transforms infrastructure management from manual commands to conversational interactions with AI.

What is MCP?

The Model Context Protocol (MCP) is an open protocol that enables AI assistants to interact with external systems through a standardized interface. StackWiz MCP implements this protocol to give AI assistants direct access to Docker infrastructure management capabilities.

Key Benefits

  • Conversational Infrastructure: Deploy services by simply describing what you need
  • Automated Best Practices: Consistent security, networking, and configuration
  • Intelligent Defaults: Smart detection of requirements and configurations
  • Safety First: Built-in validation and error prevention
  • Full Lifecycle Management: Create, monitor, update, and remove services

Table of Contents

  1. Installation & Setup
  2. Usage Guide
  3. Tool Reference
  4. Examples & Workflows
  5. Development Guide
  6. Troubleshooting

Quick Start

Prerequisites

  • Python 3.8 or higher
  • Docker and Docker Compose installed
  • Access to /srv/dockerdata directory
  • User in docker group
  • Claude Desktop or compatible MCP client

Basic Installation

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

# Install the package
pip install -e .

# Verify installation
python -m stackwiz_mcp --version

Configure Claude Desktop

Add to ~/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"
      }
    }
  }
}

First Deployment

Once configured, you can ask Claude:

"Create a new Grafana monitoring service with DNS and automatic SSL"

Claude will: 1. Create the stack directory structure 2. Generate Docker Compose configuration 3. Set up Traefik labels for SSL 4. Create Cloudflare DNS record 5. Start the service 6. Provide access details

Core Features

1. Stack Management

StackWiz MCP provides complete lifecycle management for Docker services:

  • Create: Deploy any Docker container with proper configuration
  • List: View all stacks with real-time status
  • Manage: Start, stop, restart, remove services
  • Monitor: Access logs and health status
  • Update: Modify configurations safely

2. Service Types

Generic Services

Any Docker container can be deployed: - Web applications (Grafana, n8n, Ghost) - Databases (PostgreSQL, MySQL, Redis) - Development tools (GitLab, Jenkins) - Custom applications

Pocketbase Stacks

Specialized support for Pocketbase applications: - Backend API with SQLite database - Optional frontend service - Automatic backup configuration - Built-in authentication and admin UI

3. DNS Automation

Integrated Cloudflare DNS management: - Automatic A record creation - Support for all record types - Smart IP detection - Proxy configuration

4. Infrastructure Integration

Seamless integration with existing infrastructure: - Traefik: Automatic SSL/TLS with Let's Encrypt - Docker Networks: Proper isolation and communication - Backup System: Integration with infrastructure backups - Monitoring: Prometheus metrics export

Architecture

StackWiz MCP Server
├── MCP Interface Layer
│   ├── Tools (create, list, manage)
│   ├── Resources (templates, configs)
│   └── Prompts (guided workflows)
├── Core Logic
│   ├── Stack Management
│   ├── DNS Operations
│   └── Validation Engine
└── Infrastructure Layer
    ├── Docker API
    ├── File System
    └── External APIs

How It Works

  1. AI Request: You ask Claude to deploy a service
  2. MCP Processing: StackWiz interprets the request
  3. Validation: Configuration is validated for safety
  4. Execution: Docker commands are executed
  5. Feedback: Results and access details provided

Example Interactions

Simple Deployment

"I need a PostgreSQL database for my application"

Complex Stack

"Create a complete web application with Pocketbase backend and React frontend, both with SSL and proper domains"

Management Tasks

"Show me all running services and their resource usage"

Troubleshooting

"Why is my Grafana service not accessible? Check the logs"

Security Considerations

  • All inputs are validated to prevent injection attacks
  • File operations restricted to base directory
  • Sensitive environment variables are never logged
  • Proper Unix permissions (750 for directories, 640 for files)
  • Docker socket access controlled by group membership

Next Steps

Support