MCP Composer

MCP Composer

MCP Composer 是一项网关服务，可集中管理所有 MCP 服务。你可以用它整合所需的所有 MCP 服务，并为每项需要访问 MCP 服务的服务（如 AI Agent 或工具）开放独立端口，并为其配置不同的服务和工具组合。

主要功能

• 动态管理 MCP 服务：动态管理与多个 MCP 服务及其工具的连接，支持按需启用或停用服务。
• 统一 MCP 端点：公开单个 Streamable HTTP 端点（支持最新的 MCP 协议 2026-07-28 以及更早的修订版本），以访问所有受管理 MCP 服务的功能。还提供传统 SSE 端点，供尚不支持 Streamable HTTP 的客户端使用。
• 多个动态端点：支持动态创建和移除多个网关端点，以满足不同 AI Agent 或 AI 工具的需求。
• 独立的接口配置：每个网关独立管理自己的 MCP 服务和工具组合，从而提供定制化服务。

系统架构

关键术语

• MCP 客户端：外部工具或 AI Agent 和 AI 工作流，例如 Cursor、n8n 等。
• Gateway[A/B]：绑定到 ServerKit 并由 Composer 管理的 MCP 服务实现，用于处理 MCP 客户端连接。
• Server Kit：管理和控制下游 MCP 服务的信息，以及服务中应启用的工具。
• 下游控制器：负责控制和管理与下游 MCP 服务的连接。
• 下游 MCP 服务：连接到下游 MCP 服务的内部对象，通过内部 MCP 客户端实现与下游 MCP 服务的连接。
• MCP 服务：外部 MCP 服务，例如：https://github.com/modelcontextprotocol/servers 等。
• Composer：提供用于控制和协调网关、Server Kit 和下游控制器的 API。

要求

• Python >= 3.12
• uv：快速的 Python 包安装器和管理器。

安装

方法 1：

1. 克隆代码库：

   git clone https://github.com/htkuan/mcp-composer
   cd mcp-composer
   

2. 安装依赖项： 使用 uv 同步项目依赖项。

   make install
   # 或直接使用 uv
   # uv sync
   

方法 2：

使用 Docker Compose 代替本地 Python/uv 环境；请参阅使用 Docker Compose 运行。

配置

运行应用程序之前，需要配置目标 MCP 服务。

1. 复制示例配置文件：

   cp mcp_servers.example.json mcp_servers.json
   

2. 编辑 mcp_servers.json，填写要连接的 MCP 服务的详细信息。

   • 本地服务使用 command / args / env（stdio 传输）。
   • 远程服务使用 url。默认先尝试 Streamable HTTP 传输，失败后回退到传统 SSE 传输。设置 "type": "http" 或 "type": "sse" 可强制使用指定传输方式。
   • 系统会自动协商各下游服务支持的最新协议版本，因此使用旧版 MCP SDK 构建的服务仍可正常工作。

3. 设置环境变量：

   cp .env.example .env
   

4. 编辑 .env 文件以配置以下设置：

   • HOST：服务主机地址（默认值：0.0.0.0）
   • PORT：服务端口（默认值：8000）
   • MCP_COMPOSER_PROXY_URL：MCP Composer 代理 URL（默认值：http://localhost:8000）
   • MCP_SERVERS_CONFIG_PATH：MCP 服务配置文件的路径（默认值：./mcp_servers.json）

运行

使用 uv 运行 FastAPI 应用：

make run
# or directly use uv
# uv run src/main.py

服务启动后，你可以在浏览器中通过 API 文档与 API 交互（通常位于 http://127.0.0.1:8000/docs）。

每个网关都提供两个 MCP 端点（默认网关名为 composer）：

• Streamable HTTP（推荐）：http://127.0.0.1:8000/mcp/{gateway_name}/mcp
• SSE（旧版）：http://127.0.0.1:8000/mcp/{gateway_name}/sse

使用 Docker Compose 运行

Docker 镜像内置了 Python、uv/uvx、Node.js/npx 和 Docker CLI，因此通过 uvx、npx 或 docker run 启动的 stdio 服务可以在容器内运行。

1. 按照配置中的说明创建 mcp_servers.json。项目目录会挂载到容器中，因此文件会从 /app/mcp_servers.json 读取。

2. 构建并启动服务：

   make run-docker
   # 或直接使用 docker compose
   # docker compose up -d --build
   

   拉取新更改后，运行 docker compose up -d --build 以重新构建镜像。

3. 检查状态和日志：

   docker compose ps                    # 服务就绪后，STATUS 会显示 "(healthy)"
   docker compose logs -f mcp-composer  # 显示已连接的下游服务
   

   UI、API 文档和网关端点的地址与运行部分中的相同。

4. 停止服务：

   docker compose down
   

注意：

• 代码更改：src/ 挂载自你的工作副本，因此更改代码或 mcp_servers.json 后，运行 docker compose restart 即可生效，无需重新构建。
• 访问本机上的服务：在容器内，localhost 指向容器本身。请改用 host.docker.internal，例如 "url": "http://host.docker.internal:8001/mcp"。这也适用于 docker run 条目启动的容器。在 Linux 上，请将 extra_hosts: ["host.docker.internal:host-gateway"] 添加到 docker-compose.yml 中的服务配置。
• 基于 Docker 的 MCP 服务：宿主机的 Docker 套接字已挂载，因此 "command": "docker" 条目会在宿主机上启动同级容器。这会让容器完全访问你的 Docker 守护进程。
• 环境变量：MCP_SERVERS_CONFIG_PATH 和 MCP_COMPOSER_PROXY_URL 在 docker-compose.yml 中设置，其优先级高于 .env。发布端口固定为 8000:8000；如果更改 PORT，也要相应更新 ports。

开发

项目包含一个 Makefile，用于简化常见的开发任务：

• 安装依赖：make install
• 格式化并检查代码：make format（使用 Ruff）
• 运行应用：make run
• 使用 Docker Compose 运行：make run-docker

贡献

欢迎为本项目贡献！请遵循标准的 GitHub Fork & Pull Request 工作流。建议在提交 Pull Request 之前先创建一个 Issue 进行讨论。