MCP Server Unified Deployment

English | 中文

A unified deployment and management tool for MCP (Model Context Protocol) servers. This project converts MCP servers deployed in various forms (uvx, npx, etc.) into a standardized SSE (Server-Sent Events) deployment, facilitating unified invocation by different tools.

Table of Contents

• Features
• Prerequisites
• Installation
• Configuration
  • Server Types
  • Environment Variables
• Usage
  • Basic Commands
  • Example
  • Integrate Configuration Generator Script
  • Monitoring
• Client Configuration
• Directory Structure
• Docker Support
  • Docker Deployment Options
  • Using Docker for Development
  • Production Deployment with Pre-Built Images
  • Production Deployment with Docker Compose
• Contributing
• License

中文导航

• MCP服务器统一部署工具
  • 特性
  • 前提条件
  • 安装
  • 配置
    • 服务器类型
    • 环境变量
  • 使用方法
    • 基本命令
    • 示例
  • 客户端配置
  • 目录结构
  • Docker支持
  • 贡献
  • 许可证

Features

• Unified Management: Manage multiple MCP servers from a single interface
• SSE Standardization: Convert various MCP server implementations to SSE protocol
• Cross-Platform: Works on Windows, macOS, and Linux
• Flexible Configuration: Easy configuration for different server types and environments

MCP Server Unified Deployment

Features

• Unified Management: Manage multiple MCP servers from a single interface
• SSE Standardization: Convert various MCP server implementations to SSE protocol
• Cross-Platform: Works on Windows, macOS, and Linux
• Flexible Configuration: Easy configuration for different server types and environments
• Process Management: Start, stop, restart, and check status of MCP servers
• Docker Support: Comprehensive Docker deployment and management options
• GitHub Workflow Integration: CI/CD pipeline for automated testing and deployment

Prerequisites

• Python 3.12+

• Git (for source code type servers)

• Node.js and npm (for Node.js based servers)

• uv (for dependency management)

• pipx (for installing mcp-proxy, it is recommended that mcp-proxy be installed through pipx).

• uvx (for uvx based servers)

• Docker and Docker Compose (optional, for containerized deployment)

Installation

1. Clone this repository:

git clone https://github.com/BigUncle/MCP-Server-Unified-Deployment.git
cd MCP-Server-Unified-Deployment

2. Set up a virtual environment and install dependencies using uv:

# Install uv if you don't have it
pip install uv


# Create a virtual environment
uv venv --python=3.12

# install from requirements.txt
uv pip install -r requirements.txt
# OR install dependencies with uv
# uv pip install -e .


# Activate the virtual environment (Windows)
.venv\Scripts\activate
# OR Activate the virtual environment (Linux/MacOS)
# source .venv/bin/activate

Alternatively, you can use our setup script:

python scripts/setup_env.py

3. Install mcp-proxy using pipx (recommended):

# Install pipx if you don't have it
pip install pipx
pipx ensurepath

# Install mcp-proxy
pipx install mcp-proxy

4. Create your configuration file:

cp config/mcp_servers.example.json config/mcp_servers.json

5. Edit the configuration file to match your requirements.

Configuration

The configuration file (config/mcp_servers.json) contains settings for all MCP servers you want to manage. Each server entry includes:

{
  "name": "server-name",         // Unique name for the server
  "enabled": true,              // Whether the server is enabled
  "type": "uvx",                // Server type (uvx, node, source_code, etc.)
  "sse_host": "localhost",      // Host for SSE endpoint
  "sse_port": 23001,            // Port for SSE endpoint
  "allow_origin": "*",          // CORS setting for SSE endpoint
  "install_commands": [          // Commands to install the server
    "uvx -v mcp-server-fetch"
  ],
  "sse_start_command": "mcp-proxy {start_command} --sse-host={sse_host} --sse-port={sse_port} --allow-origin='{allow_origin}' ",  // Command template for SSE mode
  "start_command": "uvx mcp-server-fetch",  // Original start command
  "env": {},                    // Environment variables for the server
  "working_directory": "",      // Optional working directory for running commands
  "repo_url": "",               // For source_code type, git repository URL
  "branch": "main"              // For source_code type, git branch to use
}

Server Types

• uvx: Servers deployed using uvx
• node: Node.js based servers
• source_code: Servers that need to be built from source code
• docker: Servers that run in Docker containers

Environment Variables

You can specify environment variables for each server in the env section:

"env": {
  "NODE_ENV": "production",
  "DEBUG": "true"
}

Usage

Basic Commands

# Start all enabled servers
python scripts/manage_mcp.py start

# Start a specific server
python scripts/manage_mcp.py start <server-name>

# Stop all servers
python scripts/manage_mcp.py stop

# Stop a specific server
python scripts/manage_mcp.py stop <server-name>

# Restart a specific server
python scripts/manage_mcp.py restart <server-name>

# Check status of all servers
python scripts/manage_mcp.py status

Example

To start the fetch server:

python scripts/manage_mcp.py start fetch

Integrate Configuration Generator Script

The integrate_config_generator.py script is used to generate client-specific configuration files based on the mcp_servers.json file. It reads the mcp_servers.json file and generates client-specific configuration files in the config/client_configs/ directory.

Usage

python scripts/integrate_config_generator.py

This script will create configuration files for each client found in the mcp_servers.json file and place them in the config/client_configs/ directory. The generated configuration files are named mcp_<client>_*.json, where <client> is the name of the client. You can then use these configuration files to configure your client.

Directory Structure

.
├── config
│   ├── host_info.json            # Host info cache (auto-generated, used for network/config assist)
│   ├── mcp_servers.example.json  # Example MCP server configuration
│   ├── mcp_servers.json          # Main MCP server configuration
│   └── client_configs/           # Client configuration files generated by integrate_config_generator.py
|          └── mcp_<client>_*.json # Client configuration files
├── docker
│   ├── docker-compose.yml        # Production Docker Compose configuration
│   ├── Dockerfile                # Production Docker image build file
│   ├── entrypoint.sh             # Container entrypoint script
│   └── README.md                 # Docker-related documentation
├── docker-dev
│   ├── docker-compose.yml        # Development Docker Compose configuration
│   ├── Dockerfile                # Development Docker image build file
│   └── .devcontainer             # Devcontainer directory
│       └─ devcontainer.json      # VS Code devcontainer configuration
├── docs/                         # Project documentation
├── logs/                         # Server runtime logs
├── mcp-data/                     # Runtime data storage (if needed)
├── mcp-servers/                  # MCP server source code (if any)
├── node-modules/                 # Node.js dependencies (if needed)
├── npm-global                    # Global npm dependencies and cache
│   ├── bin
│   ├── _cacache
│   ├── lib
│   ├── _logs
│   ├── _npx
├── pids/                         # Process ID files
├── scripts
│   ├── mcp_manager               # Management modules (commands, config, process utils, etc.)
│   │   ├── commands.py           # Command modules
│   │   ├── config.py             # Configuration modules
│   │   └── process_utils.py      # Process utilities
│   ├── container_startup.py      # Container startup helper script
│   ├── detect_host_ip.py         # Host IP detection script
│   ├── integrate_config_generator.py # Client config generator script
│   ├── manage_mcp.py             # Main MCP management script
│   └── setup_env.py              # Environment setup script
├── uv-cache/                     # Python dependency cache (auto-generated by uv)
├── README.md                     # Project documentation
└── requirements.txt              # Python dependency list

Notes:

• config/client_configs/: Stores client-specific configuration files generated by integrate_config_generator.py.
• config/host_info.json: Auto-generated host info cache, used for network configuration and automation.
• docker/ and docker-dev/: Production and development Docker configurations for easy environment switching.
• mcp-servers/: Place your custom or extended MCP server source code here if needed.
• scripts/: All management, automation, and configuration scripts. The main entry point is manage_mcp.py.
• Other directories like logs/, pids/, mcp-data/, uv-cache/ are for runtime or cache data and do not require manual maintenance.

Docker Support

This project provides comprehensive Docker support for both development and deployment environments.

Docker Deployment Options

1. Development Environment:

   • A development container with all necessary tools pre-installed
   • Visual Studio Code integration via devcontainer configuration

2. Production Deployment:

   • Multi-container setup with Docker Compose
   • Individual server containers with proper isolation
   • Persistent volume management for data and configurations

Using Docker for Development

To start the development environment:

# Start the development container
docker compose -f docker-dev/docker-compose.yml up -d

# Connect to the container
docker exec -it mcp-dev zsh

Production Deployment with pre-built images

To deploy in a production environment, you can use pre-built images from Docker Hub.

docker pull biguncle2018/mcp-server-unified:latest

# Start the production container
docker run -d --name mcp-server-unified biguncle2018/mcp-server-unified:latest

# View logs
docker logs -f mcp-server-unified

# Connect to the container
docker exec -it mcp-server-unified zsh

Production Deployment with Docker Compose

To deploy in a production environment:

Configuration

Copy the example configuration file:

cp config/mcp_servers.example.json config/mcp_servers.json

Or edit the configuration file as needed.

Modify Dockerfile

If necessary, modify the Dockerfile or docker-compose.yml in the docker/ directory to suit your needs. For example, you may need to adjust the ENTRYPOINT or REAL_HOST_IP variables or TIME ZONE variables.

Build and Start Containers

# Build and start all containers
docker compose -f docker/docker-compose.yml up -d

# View logs
docker compose -f docker/docker-compose.yml logs -f

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

MCP服务器统一部署工具

English | 中文

这是一个用于统一部署和管理MCP（Model Context Protocol）服务器的工具。该项目将以不同形式（uvx、npx等）部署的MCP服务器统一转换为标准化的SSE（Server-Sent Events）部署方式，方便不同工具的统一调用。

特性

• 统一管理：通过单一界面管理多个MCP服务器
• SSE标准化：将各种MCP服务器实现转换为SSE协议
• 跨平台：支持Windows、macOS和Linux
• 灵活配置：轻松配置不同类型和环境的服务器
• 进程管理：启动、停止、重启和检查MCP服务器状态
• Docker支持：全面的Docker部署和管理选项
• GitHub工作流集成：自动化测试和部署的CI/CD管道

前提条件

• Python 3.12+
• Git（用于源代码类型服务器）
• Node.js和npm（用于基于Node.js的服务器）
• uv（用于依赖管理）
• pipx（用于安装mcp-proxy）
• uvx（用于基于uvx的服务器）
• Docker和Docker Compose（可选，用于容器化部署）

安装

1. 克隆此仓库：

git clone https://github.com/BigUncle/MCP-Server-Unified-Deployment.git
cd MCP-Server-Unified-Deployment

2. 使用uv设置虚拟环境并安装所需的Python依赖：

# 如果没有安装uv，先安装uv
pip install uv

# 创建虚拟环境
uv venv --python=3.12

# 使用uv安装依赖
uv pip install -r requirements.txt

# 激活虚拟环境（Windows）
.venv\Scripts\activate
# 或激活虚拟环境（Linux/MacOS）
# source .venv/bin/activate

或者，您可以使用我们的设置脚本：

python scripts/setup_env.py

3. 使用pipx安装mcp-proxy（推荐）：

# 如果没有安装pipx，先安装pipx
pip install pipx
pipx ensurepath

# 安装mcp-proxy
pipx install mcp-proxy

4. 创建配置文件：

cp config/mcp_servers.example.json config/mcp_servers.json

5. 编辑配置文件以满足您的需求。

配置

配置文件（config/mcp_servers.json）包含您想要管理的所有MCP服务器的设置。每个服务器条目包括：

{
  "name": "server-name",         // 服务器的唯一名称
  "enabled": true,              // 服务器是否启用
  "type": "uvx",                // 服务器类型（uvx、node、source_code等）
  "sse_host": "localhost",      // SSE端点的主机
  "sse_port": 23001,            // SSE端点的端口
  "allow_origin": "*",          // SSE端点的CORS设置
  "install_commands": [          // 安装服务器的命令
    "uvx -v mcp-server-fetch"
  ],
  "sse_start_command": "mcp-proxy {start_command} --sse-host={sse_host} --sse-port={sse_port} --allow-origin='{allow_origin}' ",  // SSE模式的命令模板
  "start_command": "uvx mcp-server-fetch",  // 原始启动命令
  "env": {},                    // 服务器的环境变量
  "working_directory": "",      // 运行命令的可选工作目录
  "repo_url": "",               // 对于source_code类型，git仓库URL
  "branch": "main"              // 对于source_code类型，使用的git分支
}

服务器类型

• uvx：使用uvx部署的服务器
• node：基于Node.js的服务器
• source_code：需要从源代码构建的服务器
• docker：在Docker容器中运行的服务器

环境变量

您可以在env部分为每个服务器指定环境变量：

"env": {
  "NODE_ENV": "production",
  "DEBUG": "true"
}

使用方法

基本命令

# 启动所有已启用的服务器
python scripts/manage_mcp.py start

# 启动特定服务器
python scripts/manage_mcp.py start <server-name>

# 停止所有服务器
python scripts/manage_mcp.py stop

# 停止特定服务器
python scripts/manage_mcp.py stop <server-name>

# 重启特定服务器
python scripts/manage_mcp.py restart <server-name>

# 检查所有服务器的状态
python scripts/manage_mcp.py status

示例

启动fetch服务器：

python scripts/manage_mcp.py start fetch

目录结构

.
├── config/                       # 配置文件
│   ├── host_info.json            # 主机信息缓存文件（自动生成/用于辅助配置）
│   ├── mcp_servers.example.json  # MCP服务器配置示例
│   ├── mcp_servers.json          # MCP服务器主配置文件
|   └── client_configs/      # 由integrate_config_generator.py生成的客户端配置
|        └── mcp_<client>_*.json # 客户端配置文件
├── docker
│   ├── docker-compose.yml        # 生产环境 Docker Compose 配置
│   ├── Dockerfile                # 生产环境 Docker 镜像构建文件
│   ├── entrypoint.sh             # 容器入口脚本
│   └── README.md                 # Docker 相关说明文档
├── docker-dev
│   ├── docker-compose.yml        # 开发环境 Docker Compose 配置
│   ├── Dockerfile                # 开发环境 Docker 镜像构建文件
│   └── .devcontainer             # 容器目录
│       └─ devcontainer.json      # devcontainer.json
├── docs/                         # 项目文档目录
├── logs/                         # 服务器运行日志目录
├── mcp-data/                     # 运行时数据存储目录（如有需要）
├── mcp-servers/                  # MCP服务器源代码目录（如有需要）
├── node-modules/                 # Node.js 依赖目录（如有需要）
├── npm-global                    # 全局 npm 依赖及缓存目录
│   ├── bin
│   ├── _cacache
│   ├── lib
│   ├── _logs
│   ├── _npx
├── pids/                         # 进程ID文件目录
├── scripts
│   ├── mcp_manager/              # 管理模块（如命令、配置、进程工具等）
│   │   ├── commands.py           # 
│   │   ├── config.py             # 配置管理
│   │   └── process_utils.py      # 进程工具
│   ├── container_startup.py      # 容器启动辅助脚本
│   ├── detect_host_ip.py         # 主机IP检测脚本
│   ├── integrate_config_generator.py # 客户端配置生成脚本
│   ├── manage_mcp.py             # MCP统一管理主脚本
│   └── setup_env.py              # 环境初始化脚本
├── uv-cache/                     # Python依赖缓存目录（uv工具自动生成）
├── README.md                     # 项目说明文档
└── requirements.txt              # Python依赖清单

Docker支持

本项目为开发和部署环境提供全面的Docker支持。

Docker部署选项

1. 开发环境：

   • 预装所有必要工具的开发容器
   • 通过devcontainer配置集成Visual Studio Code

2. 生产部署：

   • 使用Docker Compose的多容器设置
   • 具有适当隔离的单独服务器容器
   • 用于数据和配置的持久卷管理

使用Docker进行开发

启动开发环境：

# 启动开发容器
docker compose -f docker-dev/docker-compose.yml up -d

# 连接到容器
docker exec -it mcp-dev zsh

拉取项目镜像生产部署

见 镜像部署推荐流程

使用Docker compose 进行生产部署

在生产环境中部署：

配置

cp config/mcp_servers.example.json config/mcp_servers.json

或者根据需求编辑配置文件。

修改Dockerfile

有需要时，修改docker/目录中的Dockerfile或docker-compose.yml以适应您的需求。 比如，您可能需要调整ENTRYPOINT或REAL_HOST_IP变量或TIME ZONE变量。

构建和启动容器

# 构建并启动所有容器
docker compose -f docker/docker-compose.yml up -d

# 查看日志
docker compose -f docker/docker-compose.yml logs -f

贡献

欢迎贡献！详情请参阅CONTRIBUTING.md。

许可证

本项目采用MIT许可证 - 详情请参阅LICENSE文件。