![Datalayer](https://datalayer.ai)

![Become a Sponsor](https://github.com/sponsors/datalayer)

✨ MCP作曲

](https://pypi.org/project/mcp-compose) ](https://github.com/datalayer/mcp-compose/actions/workflows/build.yml) ![Test Coverage](https://github.com/datalayer/mcp-compose) ](https://www.python.org/downloads/) ![License](LICENSE) ](Dockerfile)

类似于Docker Compose-编排模型上下文协议（MCP）服务器，具有管理功能、REST API和Web UI。

🎯 概述

MCP Compose是一个在统一环境中管理多个MCP服务器的综合解决方案。它提供自动发现、智能组合、协议转换、实时监控和一个漂亮的web界面，用于管理您的MCP基础设施。

关键能力

🔧 多个MCP服务器管理 -从单个界面启动、停止和监视多个MCP服务器\ 🌐 REST API -具有32个端点的完整REST API，用于编程控制\ 🎨 现代Web用户界面 -基于React的界面美观，实时更新\ 🔄 协议转换 -STDIO和SSE协议之间无缝转换\ 📊 实时监控 -实时指标、日志和健康检查\ 🔐 安全第一 -令牌认证、CORS支持、速率限制\ 📦 轻松部署 -Docker支持Docker编写编排\ 🧪 测试良好 -265+次测试，95%的测试覆盖率\ 📚 综合文档 -API完整参考、用户指南和部署指南

🚀 快速开始

安装

# Install from PyPI
pip install mcp-compose

# Or install from source
git clone https://github.com/datalayer/mcp-compose.git
cd mcp-compose
pip install -e .

使用Docker（推荐）

# Clone repository
git clone https://github.com/datalayer/mcp-compose.git
cd mcp-compose

# Start with docker-compose (includes Prometheus & Grafana)
docker-compose up -d

# Access the Web UI
open http://localhost:8000

使用CLI

# Start the server with Web UI
mcp-compose serve --config examples/ui/mcp_compose.toml

# Access Web UI at http://localhost:8000
# Access API at http://localhost:8000/api/v1
# Access API docs at http://localhost:8000/docs

# Discover available MCP servers
mcp-compose discover

# Invoke a tool
mcp-compose invoke-tool calculator:add '{"a": 5, "b": 3}'

使用Python API

from mcp_compose import MCPServerComposer

# Create composer and start servers
composer = MCPServerComposer()
composer.load_config("config.toml")

# Start all servers
for server in composer.servers.values():
    await composer.start_server(server.name)

# List available tools
tools = await composer.list_tools()
print(f"Available tools: {[t.name for t in tools]}")

# Invoke a tool
result = await composer.invoke_tool("calculator:add", {"a": 5, "b": 3})
print(f"Result: {result}")

🎨 Web UI功能

现代网络界面提供：

📊 仪表板 -所有服务器、工具和系统指标概述
🖥️ 服务器管理 -启动、停止、重启具有实时状态的服务器
🔧 工具浏览器 -使用交互式表单搜索和调用工具
⚙️ 配置编辑器 -编辑和验证配置文件
📋 日志查看器 -具有过滤功能的实时日志流
📈 指标仪表板 -CPU、内存和请求指标图表
🔄 翻译管理 -创建和管理协议转换器
⚙️ 设置 -配置主题、API设置和首选项

📖 文档

用户指南 -使用MCP Compose的完整指南
API 参考 -完整的REST API和Python API文档
部署指南 -使用Docker和Kubernetes进行生产部署
建筑 -系统架构和设计决策

💡 您可以使用MCP Compose做什么？

本地AI开发环境：使用一个命令在笔记本电脑上启动多个MCP服务器（工具、数据源、代理），实时检查它们，并加快迭代速度。
代理工具生态系统：将来自多个MCP服务器的工具组合并公开到一个统一的AI代理界面中，并制定明确的冲突解决策略。
协议桥接：通过STDIO运行传统或基于CLI的MCP服务器，同时通过SSE将其暴露给现代客户端，而无需重写任何内容。
团队和平台工作流程：使用Docker、令牌和共享控制平面，规范MCP服务器在团队中的启动、监控和安全方式。
可观察性和调试：通过Web UI或REST API实时跟踪日志、指标和服务器运行状况，非常适合诊断代理运行期间的工具行为。
生产就绪编排：部署多个具有身份验证、监控和生命周期管理的MCP服务器，而无需构建自定义粘合代码。

✨ 实现这些用例的关键功能：

统一的多服务器启动/停止/监控
REST API+现代基于React的Web用户界面
工具发现和智能组合
通过Python API进行编程控制
实时指标、日志和监控

🏗️ 建筑

┌─────────────────────────────────────────────────────────────┐
│                         Web UI (React)                       │
│  Dashboard │ Servers │ Tools │ Config │ Logs │ Metrics      │
└──────────────────────────┬──────────────────────────────────┘
                           │ HTTP/WebSocket
┌──────────────────────────┴──────────────────────────────────┐
│                    REST API (FastAPI)                        │
│  /servers │ /tools │ /config │ /translators │ /metrics      │
└──────────────────────────┬──────────────────────────────────┘
                           │
┌──────────────────────────┴──────────────────────────────────┐
│                 MCP Compose Core                     │
│  Server Manager │ Tool Broker │ Config Manager              │
└───────┬──────────┬──────────┬──────────┬────────────────────┘
        │          │          │          │
   ┌────┴───┐ ┌───┴────┐ ┌───┴────┐ ┌───┴────┐
   │ Server │ │ Server │ │ Server │ │ Server │
   │   A    │ │   B    │ │   C    │ │   D    │
   └────────┘ └────────┘ └────────┘ └────────┘

✨ 核心功能

服务器管理

✨ 核心功能

服务器管理

多服务器编排 -同时运行多个MCP服务器
生命周期管理 -启动、停止、重新启动和监视服务器运行状况
自动重启 -自动重启故障服务器
环境隔离 -每台服务器都在自己的隔离环境中运行
配置热重新加载 -更新配置而不重新启动

工具和提示组合

自动发现 -从所有正在运行的服务器中查找工具和提示
智能组合 -整合来自多个来源的能力
冲突解决 -使用前缀/后缀/覆盖策略处理命名冲突
动态加载 -服务器启动时出现工具
统一界面 -访问所有工具的单个API

协议转换

工作室↔ SSE -在不同传输协议之间进行转换
透明网桥 -无需对现有服务器进行更改
双向 -全面的请求/响应支持
多名译员 -同时运行多个翻译器

监测和可观察性

实时度量 -CPU、内存、请求率和延迟
结构化日志记录 -带有相关ID的JSON日志
健康检查 -持续监控服务器运行状况
普罗米修斯集成 -Prometheus的导出指标
WebSocket流媒体 -实时日志和指标更新

安全

令牌身份验证 -安全的API访问
CORS支持 -可配置的源策略
速率限制 -防止滥用
输入验证 -全面的请求验证
非根容器 -以无特权用户身份运行

🛠️ 配置

创建 mcp_compose.toml:

[composer]
name = "my-composer"
conflict_resolution = "prefix"

[[servers]]
name = "filesystem"
command = "python"
args = ["-m", "mcp_server_filesystem", "/data"]
transport = "stdio"
auto_start = true

[[servers]]
name = "calculator"
command = "python"
args = ["-m", "mcp_server_calculator"]
transport = "stdio"
auto_start = true

[logging]
level = "INFO"
format = "json"

[security]
auth_enabled = true
cors_origins = ["http://localhost:3000"]

看用户指南了解完整的配置选项。

代理服务器类型

MCP Compose支持代理到不同类型的MCP服务器：

STDIO代理服务器

作为子进程运行的本地MCP服务器的代理：

[[servers.proxied.stdio]]
name = "calculator"
command = ["python", "mcp1.py"]
restart_policy = "on_failure"
max_restarts = 3

SSE代理服务器

使用服务器发送事件代理远程MCP服务器：

[[servers.proxied.sse]]
name = "remote-server"
url = "http://localhost:8080/sse"
auth_token = "your-token"
auth_type = "bearer"
timeout = 30
reconnect_on_failure = true
# Auto-start the server as subprocess (optional)
auto_start = true
command = ["python", "mcp_server.py"]
startup_delay = 3

HTTP代理服务器

使用HTTP流式传输到远程MCP服务器的代理：

[[servers.proxied.http]]
name = "http-server"
url = "http://localhost:8080"
protocol = "lines"  # or "streamable-http"
auth_token = "your-token"
auth_type = "bearer"
timeout = 30

流式HTTP代理服务器

使用本机MCP Streamable HTTP协议代理远程MCP服务器：

[[servers.proxied.streamable-http]]
name = "streamable-server"
url = "http://localhost:8080/mcp"
auth_token = "your-token"
auth_type = "bearer"
timeout = 30
reconnect_on_failure = true
max_reconnect_attempts = 10
health_check_enabled = false
# Auto-start the server as subprocess (optional)
auto_start = true
command = ["python", "mcp_server.py"]
startup_delay = 3

流式HTTP的优点：

支持双向流媒体的原生MCP协议
性能优于传统HTTP流
完全支持所有MCP功能（工具、资源、提示）
自动会话管理

看代理流式http示例一个完整的工作示例。

🔌 REST API

关键终点

# Health & Status
GET  /api/v1/health
GET  /api/v1/version
GET  /api/v1/status
GET  /api/v1/status/composition

# Server Management
GET  /api/v1/servers
POST /api/v1/servers/{id}/start
POST /api/v1/servers/{id}/stop
POST /api/v1/servers/{id}/restart

# Tool Management
GET  /api/v1/tools
POST /api/v1/tools/{name}/invoke

# Configuration
GET  /api/v1/config
PUT  /api/v1/config
POST /api/v1/config/validate
POST /api/v1/config/reload

# Translators
GET    /api/v1/translators
POST   /api/v1/translators
DELETE /api/v1/translators/{id}

# WebSocket
WS   /ws/logs
WS   /ws/metrics

看 API 参考以获取完整的文档。

🧪 测试

# Run all tests
make test

# Run with coverage
make test-coverage

# Run specific test
pytest tests/test_composer.py -v

# Type checking
make type-check

# Linting
make lint

📦 发展

# Clone repository
git clone https://github.com/datalayer/mcp-compose.git
cd mcp-compose

# Install development dependencies
pip install -e ".[dev]"

# Install UI dependencies
cd ui
npm install
npm run dev

# Run tests
make test

# Build UI
make build-ui

# Run server
mcp-compose serve

🐳 Docker部署

快速开始

# Build and run
docker-compose up -d

# View logs
docker-compose logs -f

# Stop
docker-compose down

生产部署

# Build with production settings
docker build -t mcp-compose:prod .

# Run with environment variables
docker run -d \
  -p 8000:8000 \
  -v $(pwd)/config.toml:/app/config.toml:ro \
  -e MCP_COMPOSER_AUTH_TOKEN=secret \
  --name mcp-compose \
  mcp-compose:prod

看部署指南用于Kubernetes和生产设置。

📚 示例

Git+文件MCP服务器

一个完整的示例，演示如何使用匿名访问编排Git和文件系统MCP服务器。

地点： examples/git-file/

特征：

Git操作（状态、日志、差异、提交）
文件系统操作（读、写、列表）
带有工具前缀的统一API
不要求进行验证
完整的Makefile，便于管理

快速入门：

cd examples/git-file
make install
make start
make open-ui

看 Git文件示例README 以获取完整的文档。

OAuth身份验证示例

使用GitHub OAuth2身份验证的生产就绪示例。

地点： references/oauth/

特征：

OAuth2身份验证流程
JWT代币
受保护的MCP服务器端点
Pydantic AI代理集成

看 MCP认证示例自述文件了解详情。

🗂️ 资源

配置文件和基础结构资源位于 resources/ 目录：

nginx.conf -Nginx反向代理配置
prometheus.yml -Prometheus指标集合
grafana/ -Grafana仪表板和数据源

📊 项目状态

第4阶段：完成✅

第13-16周交付成果：

✅ 基于React的8页现代Web UI
✅ 实时监控仪表板
✅ 带流媒体的日志查看器
✅ 使用Recharts实现指标可视化
✅ 协议转换器管理
✅ 设置和首选项
✅ 全面的文件
✅ Docker部署设置
✅ 生产就绪配置

测试覆盖范围： 95%（265+次测试）\ 代码质量： 用mypy检查类型\ 代码行： ~15000（包括用户界面）

🗺️ 路线图

完成

✅ 核心组成发动机
✅ CLI接口
✅ REST API（32个端点）
✅ Web用户界面（8页）
✅ 实时监控
✅ 协议转换
✅ Docker部署
✅ 全面的文件

未来的增强功能

🔄 自定义扩展插件系统
🔄 GraphQL API支持
🔄 高级缓存策略
🔄 分布式部署支持
🔄 增强的分析
🔄 CLI自动完成

🤝 贡献

欢迎投稿！请查看我们的贡献指南了解详情。

# Fork and clone
git clone https://github.com/YOUR_USERNAME/mcp-compose.git

# Create feature branch
git checkout -b feature/amazing-feature

# Make changes and test
make test

# Commit and push
git commit -m "Add amazing feature"
git push origin feature/amazing-feature

# Create Pull Request

📄 许可证

BSD 3条款许可证-请参阅许可证了解详情。

🙏 致谢

建立在 FastMCP 框架
受模型上下文协议规范的启发
使用React、TypeScript和Recharts构建的UI
特别感谢所有贡献者

📧 支持

文档: 完整文档
问题:
讨论:
赞助商: 成为赞助商

______________________________________________________________________

由...制作❤️ 通过数据层 composer=MCPServerComposer( composed_server_name=“统一数据服务器”， conflict_resolution=冲突解决。前缀 )

从当前目录的pyproject.toml编写

unified_server=composer.compose_from_project（）

获取详细的成分信息

summary=composer.get_composity_summary（） print（f“使用{summary\['total_tools'\]}tools创建服务器”）


#### Advanced Configuration

from pathlib import Path from mcp_compose import MCPServerComposer, ConflictResolution

Specify custom pyproject.toml location

composer = MCPServerComposer( composed_server_name="my-server", conflict_resolution=ConflictResolution.SUFFIX )

Compose with filtering

unified_server = composer.compose_from_pyproject( pyproject_path=Path("custom/pyproject.toml"), include_servers=["jupyter-mcp-server", "earthdata-mcp-server"], exclude_servers=["deprecated-server"] )

Access composed tools and prompts

tools = composer.list_tools() prompts = composer.list_prompts() source_info = composer.get_source_info()

print(f"Tools: {', '.join(tools)}") print(f"Sources: {', '.join(source_info.keys())}")


#### 仅限发现

from mcp_compose import MCPServerDiscovery

Discover MCP servers without composing

discovery = MCPServerDiscovery() servers = discovery.discover_from_pyproject("pyproject.toml")

for name, info in servers.items(): print(f"{name}: {len(info.tools)} tools, {len(info.prompts)} prompts")


## 配置

### 冲突解决策略

当多个服务器提供同名工具或提示时，您可以选择如何解决冲突：

- **前缀** （默认）：添加服务器名称作为前缀(`server1_tool_name`)
- **后缀**：添加服务器名称作为后缀(`tool_name_server1`)
- **覆盖**：最后一台服务器获胜（覆盖之前的服务器）
- **忽略**：跳过冲突项目
- **错误**：引发冲突错误

### 冲突解决示例

If two servers both have a "search" tool:

PREFIX: jupyter_mcp_server_search, earthdata_mcp_server_search

SUFFIX: search_jupyter_mcp_server, search_earthdata_mcp_server

OVERRIDE: Only the last server's "search" tool is kept


## 真实世界的例子

### 数据科学工作流程

创建一个统一的MCP服务器，将Jupyter笔记本功能与地球科学数据访问相结合：

pyproject.toml

[project] dependencies = [ "jupyter-mcp-server>=1.0.0", "earthdata-mcp-server>=0.1.0", "weather-mcp-server>=2.0.0" ]

Discover available tools

python -m mcp_compose discover

Create unified server for data science workflow

python -m mcp_compose compose \ --name "data-science-server" \ --conflict-resolution prefix \ --output unified_server.py


这将使用以下工具创建服务器：

- `jupyter_create_notebook` -创建分析笔记本
- `earthdata_search_datasets` -查找地球科学数据
- `weather_get_forecast` -访问天气数据
- 数据分析工作流的组合提示

### 开发环境

结合开发工具和文档服务器：

from mcp_compose import MCPServerComposer, ConflictResolution

composer = MCPServerComposer( composed_server_name="dev-environment", conflict_resolution=ConflictResolution.PREFIX )

Compose development-focused servers

dev_server = composer.compose_from_pyproject( include_servers=[ "code-review-mcp-server", "documentation-mcp-server", "testing-mcp-server" ] )

Access all development tools in one place

print("Available tools:", composer.list_tools())


### 自定义集成

from mcp_compose import MCPServerComposer from my_custom_server import MyMCPServer

Create composer

composer = MCPServerComposer()

Compose discovered servers

unified_server = composer.compose_from_pyproject()

Add your custom server manually if needed

composer.add_server("custom", MyMCPServer())

Get final composition summary

summary = composer.get_composition_summary() print(f"Final server has {summary['total_tools']} tools from {summary['source_servers']} sources")


## 项目结构

使用MCP Compose时，按如下方式构建项目：

my-project/ ├── pyproject.toml # Define MCP server dependencies ├── src/ │ └── my_project/ │ ├── __init__.py │ └── main.py # Use composed server ├── composed_server.py # Generated unified server (optional) └── README.md


### pyproject.toml示例

[project] name = "my-data-project" dependencies = [ "jupyter-mcp-server>=1.0.0", "earthdata-mcp-server>=0.1.0", "fastmcp>=1.2.0" ]

[project.optional-dependencies] dev = [ "pytest>=7.0.0", "mcp-compose>=1.0.0" ]


## 错误处理

该库提供全面的错误处理：

from mcp_compose import MCPServerComposer, MCPComposerError, MCPDiscoveryError

try: composer = MCPServerComposer() server = composer.compose_from_pyproject() except MCPDiscoveryError as e: print(f"Discovery failed: {e}") print(f"Search paths: {e.search_paths}") except MCPComposerError as e: print(f"Composition failed: {e}") print(f"Server count: {e.server_count}")


## 故障排除

### 常见问题

1. **未找到MCP服务器**：确保您的依赖项包含名称中包含“mcp”的包
1. **导入错误**：检查MCP服务器软件包是否已正确安装
1. **命名冲突**：使用适当的冲突解决策略
1. **缺少工具**：验证服务器包是否导出 `app` 变量

### 调试模式

Enable verbose logging

python -m mcp_compose discover --verbose

Check specific package

python -c " from mcp_compose import MCPServerDiscovery discovery = MCPServerDiscovery() result = discovery._analyze_mcp_server('your-package-name') print(result) "

API Reference