🚀 YIXZ-MCP 节点聚合管理平台

YIXZ-MCP 是一个轻量级的 Model Context Protocol (MCP) 节点聚合管理工具。它允许你管理多个 MCP 服务节点（支持 SSE 在线服务和本地 stdio 命令），并将它们聚合为一个统一的 SSE 接入地址。

通过这个工具，你只需在xiaozhi.me控制台获取接入地址，填入实例后即可同时使用所有集成的 MCP 工具。

📌 本仓库说明

本仓库是 NasWanke/yixz-mcp-open 的部署修正版（fork 后修复）。 上游代码在 pnpm 11 + Windows 环境下无法启动，本版修复了该问题，并补充了实测内存数据与服务器选型建议。 详细修复内容见文末 🔧 启动问题修复记录。

✨ 核心功能

• 🔗 节点聚合：将分散的 MCP 服务（如本地运行的 Python 脚本、远程 SSE 服务）聚合成单一入口。

• ⚡ 统一接入：生成标准的 SSE 接入地址，完美兼容 Cursor、Trae 等支持 MCP 的客户端。

• 🔌 多协议支持：

  • SSE (Server-Sent Events): 接入现有的 MCP Web 服务。

  • Stdio (Standard Input/Output): 直接运行本地命令（如 node script.js, python script.py）。

• 📱 响应式界面：完美适配桌面端和移动端，随时随地管理节点。

• 🚀 轻量级架构：基于 Node.js + Express + Vue 3，数据存储采用 JSON 文件，无需数据库，部署极简。

Related MCP server: MCP HTTP Proxy

🚀更新日志

v0.0.3 (2025-01-30)

• 每次添加点节不用再手动重启了，会自动更新

• 自动更新的时候节点显示"连接中"状态（黄色背景显示）

• 节点状态自动轮询更新（每2秒），直到显示“已连接”就说明成功了

📝更新说明

⚡更新前请先备份MCP配置文件

# 在项目目录下,请手动备份
./api/data/instances.json

📊 实测数据与服务器选型建议

以下数据均来自真实运行实例的实测（2026-09-06），不是估算。

测试环境

实测资源占用

⚠️ 关键点：真正吃内存的不是服务本体（仅 102 MB），而是你接入的每个 MCP 子节点。评估配置时必须把节点数量算进去： 总内存 ≈ 100 MB + N × (100~300 MB)

功能验证结果（全部通过）

💡 服务器选型结论（重点：2核2G 够不够？）

结论：2核2G + Windows 是错误搭配，不推荐；同样的 2核2G 换 Linux 则完全够用。

瓶颈是内存，不是 CPU（Node 基本单线程，本应用 CPU 占用极低，2 核绰绰有余）。

为什么 Windows 不行：Windows Server 空载就要吃掉 1.3–1.8 GB，2 GB 内存几乎被系统占满，留给应用的只剩两三百 MB，随便接个 MCP 子节点就会触发 OOM 并疯狂读写页面文件，表现为"卡死/无响应"。

具体建议：

1. 🥇 首选：2核2G 就装 Linux（Alibaba Cloud Linux 3 / Ubuntu 22.04）。操作系统省下 1 GB 以上，本应用运行从容，还能稳定挂载多个 MCP 节点。而且阿里云 Windows 镜像需额外付许可证费，Linux 免费——省两笔钱。

2. 若必须用 Windows：最低 2核4G，4核8G 更从容。2G 跑 Windows 生产环境不建议。

3. 死磕 2G Windows 的唯一办法（不推荐生产）：Server Core 无桌面版 + 关闭非必要服务 + 调大页面文件，且只能接 1 个 MCP 节点，仍随时可能 OOM。

🚀 上云部署注意事项

• 不要直接用 tsx 跑生产：tsx 是即时编译 TypeScript，启动慢且多占内存。生产环境应先把 api/ 编译为 JS 再用 node 运行。

• 不要靠 run_windows.bat 常驻：用 pm2（Linux）或 nssm（Windows）托管为服务，实现崩溃自拉起与开机自启。

• 放行端口：安全组/防火墙开放 3001（或 Nginx 反向代理到 80/443）。

• 本仓库已内置 dist/：弱配置服务器可跳过 npm run build，直接启动即可对外服务，省去在 2G 机器上构建的内存压力。

• ⚠️ 凭证安全（重要）：api/data/instances.json 中存有 MCP 实例的 JWT 凭证，已被 .gitignore 排除；.env 同样已排除。部署前请务必确认没有把这两个文件提交进公开仓库。

🛠️ 部署指南

我们提供了三种部署方式，请根据你的使用场景选择最适合的一种：

方式一：一键启动脚本 (无 Docker) 🚀

适合人群：个人用户、开发者、想快速体验的用户

系统要求：

• 操作系统：Windows 10+ / macOS / Linux

• Node.js：v18 或更高版本 (下载地址)

🪟 Windows 用户

1. 下载项目

   git clone https://github.com/NasWanke/yixz-mcp-open.git
   cd yixz-mcp-open

2. 一键启动

   • 双击运行 run_windows.bat

   • 脚本会自动完成以下操作：

     • ✅ 检测 Node.js 环境

     • ✅ 安装项目依赖

     • ✅ 构建前端资源

     • ✅ 启动服务

     • ✅ 自动打开浏览器

3. 访问应用

   • 浏览器会自动打开 http://localhost:3001

   • 如需停止服务，在命令行窗口按 Ctrl + C

🍎 Mac / Linux 用户

1. 下载项目

   git clone https://github.com/NasWanke/yixz-mcp-open.git
   cd yixz-mcp-open

2. 赋予执行权限

   chmod +x run_mac.sh

3. 一键启动

   ./run_mac.sh

4. 访问应用

   • 浏览器会自动打开 http://localhost:3001

   • 如需停止服务，在终端按 Ctrl + C

⚙️ 脚本功能说明

两个脚本（run_windows.bat 和 run_mac.sh）均提供以下智能功能：

• 🔍 环境检测：自动检测 Node.js 是否安装

• 📦 智能依赖管理：

  • 首次运行自动安装依赖

  • 已安装依赖时跳过安装步骤

  • 自动检测并使用 pnpm（如果存在）

• 🏗️ 构建优化：

  • 首次运行自动构建前端

  • 已构建时跳过构建步骤

• 🚀 自动启动：服务启动后自动打开浏览器

• 🛡️ 错误处理：详细的错误提示和解决方案

📝 常见问题

访问 Node.js 官网 下载 LTS 版本安装。安装完成后重新运行脚本。

可能原因：

1. 网络问题：尝试配置 npm 镜像源 npm config set registry https://registry.npmmirror.com

2. 权限问题（Linux/Mac）：尝试使用 sudo npm install

3. Node.js 版本过低：升级到 v18+

删除 dist 文件夹后重新运行脚本即可：

• Windows: 删除 dist 文件夹

• Mac/Linux: rm -rf dist

方式二：Docker 容器化部署 🐳

适合人群：

• 熟悉 Docker 的开发者

• 需要在服务器上部署的用户

• 希望环境隔离、易于迁移的场景

系统要求：

• Docker：20.10+

• Docker Compose：2.0+

📦 快速开始

1. 安装 Docker

   • Windows/Mac：下载 Docker Desktop

   • Linux：

     curl -fsSL https://get.docker.com | sh
     sudo usermod -aG docker $USER

2. 启动服务

   # 克隆项目
   git clone https://github.com/NasWanke/yixz-mcp-open.git
   cd yixz-mcp-open
   
   # 构建并启动（后台运行）
   docker-compose up -d --build

3. 查看日志

   # 查看实时日志
   docker-compose logs -f
   
   # 查看服务状态
   docker-compose ps

4. 访问应用

   • 打开浏览器访问 http://localhost:3001

🛠️ Docker 管理命令

# 停止服务
docker-compose stop

# 启动服务
docker-compose start

# 重启服务
docker-compose restart

# 停止并删除容器
docker-compose down

# 查看资源占用
docker stats yixz-mcp-open

💾 数据持久化

• 配置数据自动保存在 ./api/data 目录

• 容器删除或重建不会丢失数据

• 备份数据只需复制 api/data 文件夹

🔧 高级配置

修改 docker-compose.yml 中的端口映射：

ports:
  - "8080:3001"  # 将 8080 映射到容器内的 3001

取消 docker-compose.yml 中 Nginx 服务的注释，配置 nginx.conf：

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://yixz-mcp:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Docker 会自动检查服务健康状态：

• 检查间隔：30 秒

• 超时时间：10 秒

• 重试次数：3 次

查看健康状态：

docker inspect --format='{{.State.Health.Status}}' yixz-mcp-open

方式三：服务器面板部署 (宝塔 / 1Panel) 🌐

适合人群：

• 使用 VPS/云服务器的用户

• 已安装宝塔或 1Panel 面板的用户

• 需要通过 Web 界面管理的场景

系统要求：

• 操作系统：CentOS / Ubuntu / Debian

• Node.js：v18+

• 面板：宝塔面板 7.x+ 或 1Panel

📋 部署步骤

1. 上传项目文件

   • 使用 Git 克隆或 FTP/SFTP 上传到服务器

   • 推荐目录：/www/wwwroot/mcp-open 或 /opt/mcp-open

   # 使用 Git 克隆
   cd /www/wwwroot
   git clone https://github.com/your-repo/yixz-mcp-open.git
   cd yixz-mcp-open

2. 安装依赖与构建

   # 安装依赖
   npm install
   
   # 构建前端资源
   npm run build
   
   # 验证构建结果
   ls -la dist/

3. 启动服务

   方式 A：宝塔面板

   • 登录宝塔面板

   • 点击左侧 网站 -> Node项目

   • 点击 添加Node项目

   • 填写配置：

     • 项目名称：yixz-mcp-open

     • 项目目录：/www/wwwroot/yixz-mcp-open

     • 启动文件：api/index.ts 或使用 package.json 的 start 脚本

     • 端口：3001

     • 运行用户：www

   • 点击 提交 并启动项目

   方式 B：1Panel

   • 登录 1Panel 面板

   • 点击 容器 -> 应用商店

   • 搜索并安装 Node.js 运行环境

   • 配置：

     • 项目目录：/opt/yixz-mcp-open

     • 启动命令：npm start

     • 端口：3001

   方式 C：命令行 PM2

   # 安装 PM2
   npm install -g pm2
   
   # 启动服务
   pm2 start npm --name "yixz-mcp-open" -- start
   
   # 设置开机自启
   pm2 startup
   pm2 save
   
   # 查看状态
   pm2 status
   pm2 logs yixz-mcp-open

4. 配置反向代理 (可选)

   如果你想通过域名访问，配置 Nginx 反向代理：

   宝塔面板：

   • 点击 网站 -> 添加站点

   • 填写域名，创建站点

   • 点击 设置 -> 反向代理

   • 添加规则：

     • 代理名称：MCP Open

     • 目标 URL：http://127.0.0.1:3001

     • 发送域名：$host

   手动配置 Nginx：

   server {
       listen 80;
       server_name your-domain.com;
   
       location / {
           proxy_pass http://127.0.0.1:3001;
           proxy_http_version 1.1;
           proxy_set_header Upgrade $http_upgrade;
           proxy_set_header Connection 'upgrade';
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
           proxy_set_header X-Forwarded-Proto $scheme;
           proxy_cache_bypass $http_upgrade;
       }
   }

5. 配置 SSL (可选)

   使用宝塔面板或 Let's Encrypt 免费证书：

   # 使用 Certbot
   sudo apt install certbot python3-certbot-nginx
   sudo certbot --nginx -d your-domain.com

🔧 服务器维护

# 查看日志
tail -f /var/log/nginx/access.log
tail -f /var/log/nginx/error.log

# 重启服务
pm2 restart yixz-mcp-open

# 重启 Nginx
sudo systemctl restart nginx

# 查看端口占用
netstat -tulnp | grep 3001

📊 性能优化建议

1. 使用 PM2 集群模式（多核 CPU）

   pm2 start npm --name "mcp-open" -i max -- start

2. 配置 Nginx 缓存（静态资源）

   location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
       expires 1y;
       add_header Cache-Control "public, immutable";
   }

3. 启用 gzip 压缩

   gzip on;
   gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;

📖 使用指南

1. 创建实例：

   • 打开首页，点击右上角“新建实例”，填写名称（如 "My Tools"）。

2. 添加节点：

   • 进入实例详情页，点击“添加节点”。

   • SSE 模式：填写远程 MCP 服务的 URL。

   • Stdio 模式：填写要执行的命令（如 npx）和参数（如 -y @modelcontextprotocol/server-filesystem c:\projects）。

3. 获取接入地址：

   • 在实例详情页顶部，复制“接入地址”（通常以 /api/mcp/{id}/sse 结尾）。

4. 配置 AI 客户端：

   • 打开 Cursor 或 Trae 的设置页面。

   • 找到 MCP 设置 -> Add new MCP server。

   • Type 选择 SSE。

   • URL 填入刚才复制的地址。

   • 点击保存，即可连接成功！

💻 开发指南

如果你想参与开发或修改源码：

# 1. 安装依赖
pnpm install

# 2. 启动开发服务器 (前后端同时启动)
pnpm run dev

• 前端地址: http://localhost:5173

• 后端地址: http://localhost:3001

🔧 启动问题修复记录

记录本仓库相对上游所做的修复，供排障参考。

问题现象

双击 run_windows.bat 后，浏览器打不开 http://localhost:3001，端口无监听。

根因

pnpm start 会先执行依赖状态检查并自动触发 pnpm install，而 pnpm ≥ 10 默认拦截依赖的 postinstall 构建脚本，导致 install 失败并中断启动：

[ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: esbuild@0.21.5, esbuild@0.27.0, esbuild@0.27.2
[ERROR] Command failed with exit code 1: ... pnpm install

服务进程从未被启动，因此端口无监听。

排查难点：原脚本用 >nul 2>&1 吞掉了全部输出，错误信息完全不可见。

修复内容

⚠️ 一个无效写法（避坑）

不要在 package.json 中添加：

"pnpm": { "onlyBuiltDependencies": ["esbuild"] }

pnpm 11 已不再读取 package.json 的 pnpm 字段，实测会告警且完全无效：

[WARN] The "pnpm" field in package.json is no longer read by pnpm.
       The following keys were ignored: "pnpm.onlyBuiltDependencies"

正确位置是 pnpm-workspace.yaml 的 allowBuilds。

排障建议

服务起不来时，第一件事是把启动输出落到日志文件，而不是丢给 >nul：

:: 错误示范 —— 报错全被吞掉，无法排障
start /B cmd /c "pnpm start >nul 2>&1"

:: 正确示范 —— 报错可见 + 独立窗口 + 关窗不死
start "YIXZ-MCP-Server" cmd /c "node_modules\.bin\tsx.cmd api\index.ts > server.log 2>&1"

随后检查 server.log 与 /health 接口即可快速定位。

📄 License

Apache-2.0 license