Labsco
phildougherty logo

MCP-Compose

★ 56

from phildougherty

Orchestration tool for managing multiple MCP servers with a Docker Compose-style interface and a unified HTTP proxy.

🔥🔥🔥🔥✓ VerifiedFreeAdvanced setup
#automation#devops#git#search#security#monitoring#translation

MCP-Compose

Go Report Card

Docker Compose for Model Context Protocol servers. Run multiple MCP servers with unified configuration, HTTP proxy, and container orchestration.

MCP-Compose Demo

Features

  • Docker Compose-style YAML configuration
  • HTTP proxy with automatic protocol translation (STDIO → HTTP)
  • Native support for Docker and Podman
  • Session management and connection pooling
  • Built-in dashboard and monitoring
  • OpenAPI spec generation

Working Examples

Basic - Filesystem + Memory

version: '1'
servers:
  filesystem:
    protocol: stdio
    command: npx
    args:
      - "-y"
      - "@modelcontextprotocol/server-filesystem"
      - "${HOME}"
    capabilities: [resources, tools]
    volumes:
      - "${HOME}:${HOME}:ro"

  memory:
    protocol: stdio
    command: npx
    args:
      - "-y"
      - "@modelcontextprotocol/server-memory"
    capabilities: [resources, tools]

Add Brave Search (requires API key from https://brave.com/search/api/):

  brave-search:
    protocol: stdio
    command: npx
    args:
      - "-y"
      - "@modelcontextprotocol/server-brave-search"
    capabilities: [tools]
    env:
      BRAVE_API_KEY: "${BRAVE_API_KEY}"
export BRAVE_API_KEY="your-api-key"
mcp-compose up

See examples/ for more configurations.

Commands

Service Management

mcp-compose up                 # Start all services
mcp-compose up filesystem      # Start specific service
mcp-compose down               # Stop all services
mcp-compose down filesystem    # Stop specific service
mcp-compose restart            # Restart all services
mcp-compose ps                 # List service status
mcp-compose logs filesystem    # View logs

System Services

System services are infrastructure components (proxy, dashboard, task-scheduler, memory).

mcp-compose system up          # Start system services
mcp-compose system down        # Stop system services
mcp-compose system ps          # List system services
mcp-compose system status      # Health overview
mcp-compose system logs proxy  # View system logs

Proxy

mcp-compose proxy --port 9876              # Start proxy
mcp-compose proxy --api-key $(openssl rand -hex 32)  # With authentication

Dashboard

mcp-compose dashboard          # Start web dashboard
# Access at http://localhost:3111

Configuration

mcp-compose init               # Interactive setup wizard
mcp-compose validate           # Validate config file
mcp-compose create-config --type claude  # Generate client config

Security

Never commit secrets to your config file. Use environment variables:

# Generate secure keys
export MCP_API_KEY=$(openssl rand -hex 32)
export OAUTH_CLIENT_SECRET=$(openssl rand -hex 32)

Reference in config:

proxy_auth:
  api_key: "${MCP_API_KEY}"

Client Integration

Claude Desktop

Generate config:

mcp-compose create-config --type claude --output ./claude-config

Copy contents to Claude Desktop settings.

Direct HTTP

# List tools
curl -X POST http://localhost:9876/filesystem \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Call tool
curl -X POST http://localhost:9876/filesystem \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"tools/call",
    "params":{
      "name":"read_file",
      "arguments":{"path":"/tmp/test.txt"}
    }
  }'

Architecture

┌──────────────────────────────┐
│     MCP-Compose Proxy        │
│  (HTTP API + Authentication) │
└──────────────┬───────────────┘
               │
        ┌──────┼──────┐
        │      │      │
    ┌───▼──┐ ┌─▼──┐ ┌▼───┐
    │ FS   │ │ Mem│ │Search│
    │STDIO │ │HTTP│ │ SSE  │
    └──────┘ └────┘ └──────┘