matfax/docker-compose-mcp

Docker Compose MCP Server

MCP server that provides lifecycle management for Docker Compose services with automatic startup, status monitoring, and graceful shutdown.

Requirements: Python (see .python-version), Docker, Docker Compose, uv

CLI Options

# Basic usage
docker-compose-mcp /path/to/project

# Use specific compose file
docker-compose-mcp /path/to/project --compose-file docker-compose.dev.yml

# Enable debug logging
docker-compose-mcp /path/to/project --debug --log-level DEBUG

# All options
docker-compose-mcp PROJECT_DIR [--compose-file FILE] [--log-level LEVEL] [--debug]

Options:

• PROJECT_DIR: Path to Docker Compose project directory
• --compose-file: Compose file name (default: docker-compose.yml)
• --log-level: Logging level - DEBUG, INFO, WARNING, ERROR (default: INFO)
• --debug: Enable debug mode with stderr logging

Adding to Claude Code

Add to your MCP settings:

{
  "mcpServers": {
    "docker-compose-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--from",
        "git+https://github.com/matfax/docker-compose-mcp.git",
        "docker-compose-mcp",
        "/path/to/your/docker-compose-project"
      ]
    }
  }
}

{
  "mcpServers": {
    "docker-compose-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--from",
        "/path/to/docker-compose-mcp",
        "docker-compose-mcp",
        "/path/to/your/docker-compose-project"
      ]
    }
  }
}

Available MCP Tools

get_compose_status

Returns current status of all services and containers:

• Service states and health status
• Container information and port mappings
• Project details

get_compose_logs

Retrieves Docker Compose logs with options:

• service (optional): Specific service name
• tail (optional): Number of log lines (default: 100)

restart_compose

Restarts all Docker Compose services.

Features

• Automatic Lifecycle Management: Auto-starts compose services on startup, stops on shutdown
• Health Monitoring: Tracks container health and port bindings
• Signal Handling: Graceful shutdown with SIGINT/SIGTERM
• Environment Loading: Automatically loads docker.env from project directory
• Security: Input validation and subprocess security for all operations
• Error Handling: Comprehensive error handling with structured logging

Environment Variables

Create a docker.env file in your project directory:

POSTGRES_DB=myapp
POSTGRES_USER=user
POSTGRES_PASSWORD=password

The MCP server automatically loads these variables when starting Docker Compose.

Lifecycle Management

• On Startup: Runs docker-compose up -d in the specified project directory
• During Operation: Provides MCP tools for monitoring and management
• On Shutdown: Gracefully runs docker-compose down to stop services
• Signal Handling: Responds to SIGINT/SIGTERM for clean shutdown

Example Usage

# Basic usage with current directory
docker-compose-mcp .

# Use with specific project and compose file
docker-compose-mcp /home/user/my-app --compose-file docker-compose.prod.yml

# Debug mode for troubleshooting
docker-compose-mcp /home/user/my-app --debug --log-level DEBUG

The server will automatically start your Docker Compose services, provide MCP tools for management, and clean up when you exit.