MCP Server Unified Deployment

## MCP Server Unified Deployment [English](#mcp-server-unified-deployment) | [中文](#mcp服务器统一部署工具) 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](#features) - [Prerequisites](#prerequisites) - [Installation](#installation) - [Configuration](#configuration) - [Server Types](#server-types) - [Environment Variables](#environment-variables-1) - [Usage](#usage) - [Basic Commands](#basic-commands) - [Example](#example) - [Integrate Configuration Generator Script](#integrate-configuration-generator-script) - [Monitoring](#monitoring) - [Client Configuration](#client-configuration) - [Directory Structure](#directory-structure) - [Docker Support](#docker-support) - [Docker Deployment Options](#docker-deployment-options) - [Using Docker for Development](#using-docker-for-development) - [Production Deployment with Pre-Built Images](#production-deployment-with-pre-built-images) - [Production Deployment with Docker Compose](#production-deployment-with-docker-compose) - [Contributing](#contributing) - [License](#license) **中文导航** - [MCP服务器统一部署工具](#mcp服务器统一部署工具) - [特性](#特性) - [前提条件](#前提条件) - [安装](#安装) - [配置](#配置) - [服务器类型](#服务器类型) - [环境变量](#环境变量-1) - [使用方法](#使用方法) - [基本命令](#基本命令) - [示例](#示例) - [客户端配置](#客户端配置) - [目录结构](#目录结构) - [Docker支持](#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: ```bash 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: ```bash # 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: ```bash python scripts/setup_env.py ``` 3. Install mcp-proxy using pipx (recommended): ```bash # 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: ```bash 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: ```json { "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: ```json "env": { "NODE_ENV": "production", "DEBUG": "true" } ``` ## Usage ### Basic Commands ```bash # 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: ```bash 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 ```bash 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: ```bash # 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. ```bash 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: ```bash 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 ```bash # 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](CONTRIBUTING.md) for details. ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. --- # MCP服务器统一部署工具 [English](#mcp-server-unified-deployment) | [中文](#mcp服务器统一部署工具) 这是一个用于统一部署和管理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. 克隆此仓库： ```bash git clone https://github.com/BigUncle/MCP-Server-Unified-Deployment.git cd MCP-Server-Unified-Deployment ``` 2. 使用uv设置虚拟环境并安装所需的Python依赖： ```bash # 如果没有安装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 ``` 或者，您可以使用我们的设置脚本： ```bash python scripts/setup_env.py ``` 3. 使用pipx安装mcp-proxy（推荐）： ```bash # 如果没有安装pipx，先安装pipx pip install pipx pipx ensurepath # 安装mcp-proxy pipx install mcp-proxy ``` 4. 创建配置文件： ```bash cp config/mcp_servers.example.json config/mcp_servers.json ``` 5. 编辑配置文件以满足您的需求。 ## 配置 配置文件（`config/mcp_servers.json`）包含您想要管理的所有MCP服务器的设置。每个服务器条目包括： ```json { "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`部分为每个服务器指定环境变量： ```json "env": { "NODE_ENV": "production", "DEBUG": "true" } ``` ## 使用方法 ### 基本命令 ```bash # 启动所有已启用的服务器 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服务器： ```bash 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进行开发 启动开发环境： ```bash # 启动开发容器 docker compose -f docker-dev/docker-compose.yml up -d # 连接到容器 docker exec -it mcp-dev zsh ``` ### 拉取项目镜像生产部署 见 [镜像部署推荐流程](docs/镜像部署推荐流程.md) ### 使用Docker compose 进行生产部署 在生产环境中部署： #### 配置 ```bash cp config/mcp_servers.example.json config/mcp_servers.json ``` 或者根据需求编辑配置文件。 #### 修改Dockerfile 有需要时，修改`docker/`目录中的`Dockerfile`或`docker-compose.yml`以适应您的需求。 比如，您可能需要调整`ENTRYPOINT`或`REAL_HOST_IP`变量或`TIME ZONE`变量。 #### 构建和启动容器 ```bash # 构建并启动所有容器 docker compose -f docker/docker-compose.yml up -d # 查看日志 docker compose -f docker/docker-compose.yml logs -f ``` ## 贡献 欢迎贡献！详情请参阅[CONTRIBUTING.md](CONTRIBUTING.md)。 ## 许可证 本项目采用MIT许可证 - 详情请参阅[LICENSE](LICENSE)文件。