mcp-compose

View on GitHub

Compose, manage, and run MCP servers as Docker containers. With a Unified API gateway built in.

58 stars GoOthers Updated Aug 16, 2026

Documentation

MCP-Compose

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

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

Installation

bash

git clone https://github.com/phildougherty/mcp-compose.git
cd mcp-compose
make build

# Add to PATH
sudo cp build/mcp-compose /usr/local/bin/
# OR
export PATH="$PWD/build:$PATH"

Quick Start

Interactive Setup

bash

mcp-compose init

Follow the prompts to create your configuration.

Manual Setup

Create `mcp-compose.yaml`:

yaml

version: '1'
servers:
  filesystem:
    protocol: stdio
    command: npx
    args:
      - "-y"
      - "@modelcontextprotocol/server-filesystem"
      - "/tmp"
    capabilities: [resources, tools]

Start servers:

bash

mcp-compose up

Start the HTTP proxy:

bash

mcp-compose proxy --port 9876

Test it:

bash

curl http://localhost:9876/api/servers

Working Examples

Basic - Filesystem + Memory

yaml

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]

With Web Search

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

yaml

brave-search:
    protocol: stdio
    command: npx
    args:
      - "-y"
      - "@modelcontextprotocol/server-brave-search"
    capabilities: [tools]
    env:
      BRAVE_API_KEY: "${BRAVE_API_KEY}"

bash

export BRAVE_API_KEY="your-api-key"
mcp-compose up

See examples/ for more configurations.

Commands

Service Management

bash

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).

bash

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

bash

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

Dashboard

bash

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

Configuration

bash

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

Configuration Reference

Basic Structure

yaml

version: '1'

# Optional: proxy authentication
proxy_auth:
  enabled: true
  api_key: "${MCP_API_KEY}"

servers:
  my-server:
    protocol: string           # stdio, http, sse
    command: string            # Executable (e.g., npx, python, node)
    args: [string]             # Command arguments
    capabilities: [string]     # tools, resources, prompts, sampling
    env:                       # Environment variables
      KEY: value
    volumes:                   # Volume mounts
      - "host:container:mode"

Protocol Types

STDIO (most common for NPM packages):

yaml

servers:
  my-server:
    protocol: stdio
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

HTTP:

yaml

servers:
  my-server:
    protocol: http
    http_port: 8080

SSE (Server-Sent Events):

yaml

servers:
  my-server:
    protocol: sse
    http_port: 8080
    sse_path: /events

Volume Mounts

yaml

volumes:
  - "/host/path:/container/path:ro"   # Read-only
  - "/host/path:/container/path:rw"   # Read-write
  - "${HOME}/code:/workspace:ro"      # Environment variables

Environment Variables

In your config:

yaml

env:
  API_KEY: "${MY_API_KEY}"

In your shell:

bash

export MY_API_KEY="secret"
mcp-compose up

Security

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

bash

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

Reference in config:

yaml

proxy_auth:
  api_key: "${MCP_API_KEY}"

Client Integration

Claude Desktop

Generate config:

bash

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

Copy contents to Claude Desktop settings.

Direct HTTP

bash

# 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"}
    }
  }'

Troubleshooting

Check Service Status

bash

mcp-compose ps
mcp-compose system status

View Logs

bash

mcp-compose logs filesystem
mcp-compose system logs proxy

Validate Configuration

bash

mcp-compose validate

Common Issues

Port already in use:

bash

lsof -i :9876
mcp-compose proxy --port 9877  # Use different port

Container not starting:

bash

mcp-compose logs my-server     # Check logs
docker ps -a                   # Check container status

Authentication errors:

bash

echo $MCP_API_KEY              # Verify key is set

Requirements

Docker 20.10+ or Podman 3.0+
Linux, macOS, or Windows with WSL2
Go 1.19+ (for building from source)

Architecture

code

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

License

GNU Affero General Public License v3.0 - see LICENSE.

Frequently asked questions

What is mcp-compose?

mcp-compose is Compose, manage, and run MCP servers as Docker containers. With a Unified API gateway built in.

How do I install mcp-compose?

Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

Is mcp-compose open source?

Yes — it is hosted on GitHub at https://github.com/phildougherty/mcp-compose and has 58 stars.

Related MCP tools

kubeshark

eBPF-powered network observability for Kubernetes. Indexes L4/L7 traffic with full K8s context, decrypts TLS without keys. Queryable by AI agents via MCP and humans via dashboard.

12,068 Go

kubernetesgolangrest+17

go-whatsapp-web-multidevice

GOWA - WhatsApp REST API with support for UI, Multi Account, Webhooks, and MCP, and Chatwoot. Built with Golang for efficient memory use.

4,717 Go

whatsappwhatsapp-apiwhatsapp-api-go+9

radar

The missing open-source Kubernetes UI with a built-in MCP server for AI agents. See what's broken, why, and what changed. Issues, Topology, event timeline, Helm, GitOps, live service traffic, and cluster audits - all in one Go binary.

3,246 Go

argocdcloud-nativegitops+17

mcp-language-server

mcp-language-server gives MCP enabled clients access semantic tools like get definition, references, rename, and diagnostics.

1,587 Go

ailanguage-server-protocolmcp+2

terraform-mcp-server

The Terraform MCP Server provides seamless integration with Terraform ecosystem, enabling advanced automation and interaction capabilities for Infrastructure as Code (IaC) development.

1,522 Go

matlab-mcp-server

Run MATLAB® using AI applications with the official MATLAB MCP Server from MathWorks®. This MCP server for MATLAB supports a wide range of coding agents like Claude Code® and Visual Studio® Code.

1,461 Go

engineering-toolsmatlabmcp-server+2

Run your own MCP server? See who uses it and what to fix.

Measure it with TrackMCP

Documentation

MCP-Compose

Features

Installation

Quick Start

Interactive Setup

Manual Setup

Working Examples

Basic - Filesystem + Memory

With Web Search

Commands

Service Management

System Services

Proxy

Dashboard

Configuration

Configuration Reference

Basic Structure

Protocol Types

Volume Mounts

Environment Variables

Security

Client Integration

Claude Desktop

Direct HTTP

Troubleshooting

Check Service Status

View Logs

Validate Configuration

Common Issues

Requirements

Architecture

License

Links

Frequently asked questions

What is mcp-compose?

How do I install mcp-compose?

Is mcp-compose open source?

Related MCP tools