MCP Docker Orchestrator

A systemd-managed daemon that orchestrates MCP (Model Context Protocol) servers as Docker containers and configures AWS ALB path-based routing.

Features

• Docker Compose Integration: Manage MCP servers using standard Docker Compose format
• AWS ALB Integration: Configure path-based routing in AWS Application Load Balancer
• Web Dashboard: Monitor and control MCP services through a web interface
• Self-healing: Automatically reconcile configuration and actual state
• Secure: No persistence of secrets, compatible with LiteLLM Proxy

Architecture

The MCP Docker Orchestrator consists of several core components:

• Configuration Manager: Handles loading and parsing of Docker Compose configuration
• Compose Manager: Manages Docker Compose service lifecycle
• ALB Manager: Configures AWS ALB routing rules
• Dashboard: Web interface for monitoring and management
• Orchestrator Service: Main process that coordinates all components

Prerequisites

• Python 3.8 or higher
• Docker and Docker Compose
• AWS Account with appropriate permissions
• Linux host (for systemd service)

Installation

Automatic Installation

The easiest way to install is using the provided setup script:

sudo ./setup.sh

This will:

1. Install Python dependencies
2. Create default configuration files
3. Set up the systemd service
4. Configure permissions

Manual Installation

1. Install Python dependencies:

   pip install -r requirements.txt
   

2. Configure settings in settings.conf

3. Configure MCP servers in mcp-compose.yaml

4. Install systemd service:

   sudo cp service.template /etc/systemd/system/mcp-orchestrator.service
   # Edit the service file to configure paths
   sudo systemctl daemon-reload
   sudo systemctl enable mcp-orchestrator.service
   

Configuration

Settings (settings.conf)

[aws]
region = us-west-2      # AWS region
alb_arn =               # ARN of your Application Load Balancer
listener_arn =          # ARN of your ALB listener
vpc_id =                # ID of your VPC

[service]
reconciliation_interval_seconds = 60  # How often to check and reconcile state
port_range_start = 8000               # Start of port range for container mapping
port_range_end = 9000                 # End of port range for container mapping

[dashboard]
username = admin        # Dashboard login username
password = changeme     # Dashboard login password (change this!)
path = /monitor         # URL path for dashboard

[logging]
level = INFO            # Logging level (DEBUG, INFO, WARNING, ERROR)

MCP Server Configuration (mcp-compose.yaml)

version: '3'

services:
  example-mcp-server:
    image: mcp/example:latest
    restart: always
    environment:
      FASTMCP_LOG_LEVEL: "ERROR"
      ADDITIONAL_ENV_VAR: "value"
    labels:
      mcp.path: "/mcp/example"
      mcp.disabled: "false"
      mcp.managed_by: "mcp-orchestrator"

Each MCP server configuration consists of:

• image: Docker image to run
• restart: Restart policy (always recommended)
• environment: Environment variables
• labels:
  • mcp.path: Path pattern for ALB routing
  • mcp.disabled: Whether this server is disabled
  • mcp.managed_by: Should always be "mcp-orchestrator"

Usage

Starting the Service

sudo systemctl start mcp-orchestrator

Checking Status

sudo systemctl status mcp-orchestrator

Viewing Logs

sudo journalctl -u mcp-orchestrator -f

Manual Execution

For testing or debugging:

# Run once and exit
python orchestrator/main.py --one-shot

# Run without dashboard
python orchestrator/main.py --no-dashboard

# Specify custom config files
python orchestrator/main.py --compose /path/to/mcp-compose.yaml --settings /path/to/settings.conf

# Migrate from old config format
python orchestrator/main.py --migrate /path/to/old/mcp.config.json

Dashboard

The web dashboard is available at:

http://your-server:5000/monitor

Default login: admin / changeme

Features:

• Overview of MCP servers
• Container status monitoring
• ALB routing configuration
• Actions (start/stop/restart services)
• Synchronization controls

Routing

Each MCP server is mapped to a path based on its ID or the mcp.path label:

/mcp/{server-id}/*

These path patterns are configured in the ALB listener rules.

Migrating from mcp.config.json

If you're upgrading from an older version that used mcp.config.json, you can use the built-in migration tool:

python orchestrator/main.py --migrate /path/to/mcp.config.json

This will:

1. Read your existing mcp.config.json
2. Convert it to the new Docker Compose format
3. Save it as mcp-compose.yaml

Troubleshooting

Container Issues

• Check Docker Compose status: docker compose ps
• Verify container logs: docker compose logs {service-id}
• Check for port conflicts
• If you see "Permission denied" errors:
  • The service user needs access to the Docker socket
  • Make sure the user is in the docker group
  • You may need to log out and log back in for group changes to take effect

AWS ALB Issues

• Verify AWS credentials
• Check ALB listener ARN and rules
• Ensure target groups are properly configured
• Check EC2 instance is registered with target groups

Service Issues

• Check systemd status: systemctl status mcp-orchestrator
• View logs: journalctl -u mcp-orchestrator -f
• Verify configuration files are properly formatted

License

This project is licensed under the MIT License - see the LICENSE file for details.