MCP-Compose

What is MCP-Compose?

MCP-Compose is a Docker Compose‑style orchestration tool for Model Context Protocol (MCP) servers. It runs multiple MCP servers with a unified YAML configuration, an HTTP proxy that automatically translates STDIO to HTTP, and full container orchestration. It is built for developers and operators who manage several MCP servers together.

How to use MCP-Compose?

Install by cloning the repository and running make build, then add the binary to your PATH. Create a mcp-compose.yaml configuration file (or run mcp-compose init for an interactive wizard). Start all servers with mcp-compose up, start the HTTP proxy with mcp-compose proxy --port 9876, and access the web dashboard with mcp-compose dashboard. Use mcp-compose create-config --type claude to generate client configuration for Claude Desktop.

Key features of MCP-Compose

• 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

Use cases of MCP-Compose

• Run multiple MCP servers with a single command
• Provide a unified HTTP API for STDIO‑based MCP servers
• Manage development MCP environments with container orchestration
• Securely expose MCP servers with proxy authentication

FAQ from MCP-Compose

What are the system requirements?

Docker 20.10+ or Podman 3.0+, Linux, macOS, or Windows with WSL2, and Go 1.19+ if building from source.

How do I authenticate the HTTP proxy?

Set proxy_auth.enabled: true and proxy_auth.api_key: "${MCP_API_KEY}" in your config file, then export the key in your shell. Alternatively, start the proxy with mcp-compose proxy --api-key $(openssl rand -hex 32).

How can I view logs or check service status?

Use mcp-compose ps to list service status, mcp-compose system status for a health overview, and mcp-compose logs <service> to view specific logs.

How do I integrate with Claude Desktop?

Run mcp-compose create-config --type claude --output ./claude-config and copy the generated configuration into Claude Desktop’s settings.

Can I start or stop only specific servers?

Yes. Use mcp-compose up <service> to start a single service and mcp-compose down <service> to stop it.