MCP Docker Orchestrator Server

A daemon to orchestrate MCP servers as Docker containers and configure AWS ALB path-based routing.

GitHub

Dokumentasi

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.