MCP-Compose
   
使用Docker Compose部署模型上下文协议（Model Context Protocol, MCP）服务器。通过统一配置、HTTP代理和容器编排来运行多个MCP服务器。
特点/特性
- Docker Compose 风格的 YAML 配置
- 带有自动协议转换功能的HTTP代理（STDIO → HTTP）
- 原生支持 Docker 和 Podman
- 会话管理和连接池
- 内置仪表板和监控功能
- OpenAPI规范生成
安装
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"快速入门
交互式设置
mcp-compose init按照提示创建您的配置。
手动设置
创建 mcp-compose.yaml:
version: '1'
servers:
filesystem:
protocol: stdio
command: npx
args:
- "-y"
- "@modelcontextprotocol/server-filesystem"
- "/tmp"
capabilities: [resources, tools]启动服务器：
mcp-compose up启动HTTP代理：
mcp-compose proxy --port 9876测试它：
curl http://localhost:9876/api/servers工作实例
基础 - 文件系统 + 内存
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]使用网页搜索
添加 Brave 搜索（需要从 https://brave.com/search/api/ 获取 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见 示例/ 以进行更多配置。
命令
服务管理
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系统服务
系统服务是基础设施组件（代理、仪表板、任务调度器、内存）。
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代理
mcp-compose proxy --port 9876 # Start proxy
mcp-compose proxy --api-key $(openssl rand -hex 32) # With authentication仪表盘
mcp-compose dashboard # Start web dashboard
# Access at http://localhost:3111配置
mcp-compose init # Interactive setup wizard
mcp-compose validate # Validate config file
mcp-compose create-config --type claude # Generate client config配置参考
基本结构
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"协议类型
STDIO（标准输入输出） （对于NPM包最常见的情况）：
servers:
my-server:
protocol: stdio
command: npx
args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]HTTP（超文本传输协议）：
servers:
my-server:
protocol: http
http_port: 8080上海证券交易所 （服务器发送事件）：
servers:
my-server:
protocol: sse
http_port: 8080
sse_path: /events卷挂载
volumes:
- "/host/path:/container/path:ro" # Read-only
- "/host/path:/container/path:rw" # Read-write
- "${HOME}/code:/workspace:ro" # Environment variables环境变量
在你的配置中：
env:
API_KEY: "${MY_API_KEY}"在你的shell中：
export MY_API_KEY="secret"
mcp-compose up安全
永远不要将机密信息存储在配置文件中。请使用环境变量：
# Generate secure keys
export MCP_API_KEY=$(openssl rand -hex 32)
export OAUTH_CLIENT_SECRET=$(openssl rand -hex 32)配置中的引用：
proxy_auth:
api_key: "${MCP_API_KEY}"客户集成
Claude Desktop（可译为“Claude桌面版”或根据具体语境简化为“Claude桌面”）
生成配置：
mcp-compose create-config --type claude --output ./claude-config将内容复制到Claude桌面设置中。
直接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"}
}
}'故障排除
检查服务状态
mcp-compose ps
mcp-compose system status查看日志
mcp-compose logs filesystem
mcp-compose system logs proxy验证配置
mcp-compose validate常见问题
端口已被使用：
lsof -i :9876
mcp-compose proxy --port 9877 # Use different port容器无法启动：
mcp-compose logs my-server # Check logs
docker ps -a # Check container status认证错误：
echo $MCP_API_KEY # Verify key is set要求
- Docker 20.10+ 或 Podman 3.0+
- Linux、macOS 或带有 WSL2 的 Windows
- Go 1.19+（用于从源代码构建）
建筑
┌──────────────────────────────┐
│ MCP-Compose Proxy │
│ (HTTP API + Authentication) │
└──────────────┬───────────────┘
│
┌──────┼──────┐
│ │ │
┌───▼──┐ ┌─▼──┐ ┌▼───┐
│ FS │ │ Mem│ │Search│
│STDIO │ │HTTP│ │ SSE │
└──────┘ └────┘ └──────┘许可证
GNU Affero 通用公共许可证 v3.0 - 请参阅 许可证.