使用说明

MCP 管理员（或 MCP 管理系统）

一个用于管理模型上下文协议（MCP）服务器的命令行界面（CLI）工具，支持Docker容器，并提供HTTP到标准输入输出（stdio）的网关。

概述

mcp-manager 通过以下方式简化MCP服务器的部署和管理：

以进程形式或在隔离的Docker容器中运行MCP服务器
为基于stdio的MCP服务器提供HTTP网关
管理服务器生命周期（启动、停止、重启）
保持MCP服务器镜像为最新版本
使用AI代理（Claude代码）注册服务器
监控服务器健康状况和状态

stdio服务器问题

许多MCP服务器被设计为通过stdio（标准输入/输出）进行通信，并在没有输入时立即退出。这与持久化的Docker容器存在根本性的不兼容问题：

问题Stdio MCP 服务器退出 → 重启策略触发 → 无限崩溃循环
解决方案mcp-manager 提供了一个 HTTP 网关，能够按需启动服务器并管理其生命周期

网关充当桥梁的角色，接收HTTP请求，并根据需要生成临时的MCP服务器进程/容器。

特点/功能

配置驱动在单个YAML文件中定义所有MCP服务器
多种部署模式：
- 持久化服务的直接容器管理
- 支持标准I/O服务器的HTTP网关，具备完整的进程和容器支持
克劳德代码集成使用 Claude Code CLI 注册/注销 MCP 服务器
会话管理按需服务器生成并自动清理
容器生命周期管理：
- 优雅地关闭并妥善清理容器
- 处理信号（SIGTERM，SIGINT）以实现优雅关闭
- 清理之前运行中遗留的容器
- 所有容器均贴有标签，便于识别
协议翻译全面支持JSON-RPC 2.0，具备正确的消息帧格式
Docker 集成容器隔离，使用附加API实现安全的服务器生成
环境变量支持通过环境变量传递密码配置
轻松更新使用单个命令更新所有服务器镜像

安装

Homebrew（适用于 macOS 和 Linux）

brew tap ihavespoons/mcp-manager
brew install mcp-manager

下载二进制文件

从（相关网站）下载预编译的二进制文件发布页面：

macOS（苹果电脑操作系统）： mcp-manager-vX.Y.Z-darwin-amd64.tar.gz (Intel) 或者 mcp-manager-vX.Y.Z-darwin-arm64.tar.gz （Apple Silicon）
Linux： mcp-manager-vX.Y.Z-linux-amd64.tar.gz (x86_64) 或者 mcp-manager-vX.Y.Z-linux-arm64.tar.gz (ARM64)
Windows: mcp-manager-vX.Y.Z-windows-amd64.zip

提取并移动到你的PATH环境变量中：

tar -xzf mcp-manager-*.tar.gz
sudo mv mcp-manager /usr/local/bin/

所有版本均包含用于验证的SHA256校验和。

来自源（或“来源”）

git clone https://github.com/ihavespoons/mcp-manager.git
cd mcp-manager
make build
# or
go build -o mcp-manager ./cmd/mcp-manager

先决条件

Go 1.25.2 或更高版本
Docker（用于基于容器的服务器）

快速入门

创建一个配置文件（mcp-config.yaml):

version: "1.0"

settings:
  data_dir: ~/.mcp-manager
  network: mcp-network
  log_level: info

servers:
  - name: filesystem
    enabled: true
    description: "Provides filesystem access capabilities"
    docker:
      image: mcp/filesystem:latest
      pull_policy: if-not-present
    command: ["mcp-server-filesystem"]
    args: ["--root", "/workspace"]
    volumes:
      - host_path: ${PWD}
        container_path: /workspace
        read_only: false
    agents:
      - claude-code

启动您的MCP服务器：

mcp-manager start

检查服务器状态：

mcp-manager status

使用方法

命令

容器管理

mcp-manager start [server-name] - 启动一个或所有MCP服务器
mcp-manager stop [server-name] - 停止一个或所有MCP服务器
mcp-manager status [server-name] - 显示MCP服务器的状态
mcp-manager list - 列出所有已配置的MCP服务器
mcp-manager logs <server-name> - 显示来自MCP服务器的日志
mcp-manager update [server-name] - 更新MCP服务器的Docker镜像
mcp-manager validate - 验证配置文件

网关

mcp-manager gateway - 启动HTTP到标准输入输出网关服务器
- --host - 网关主机地址（默认：0.0.0.0）
- --port - 网关端口（默认：8080）
- --mode - 服务器模式：容器或进程（默认：进程）
- --timeout - 会话超时（默认：30分钟）

克劳德代码集成

mcp-manager register - 使用Claude Code注册mcp-manager以及所有已启用的MCP服务器
mcp-manager unregister - 从Claude Code中注销mcp-manager和所有已配置的服务器
mcp-manager serve - 以MCP服务器（标准输入输出）模式运行mcp-manager，并集成网关

全球旗帜

-c, --config - 指定配置文件位置（默认：搜索标准位置）
-v, --verbose - 启用详细输出

示例

集装箱管理

启动所有服务器：

mcp-manager start --all

启动特定服务器：

mcp-manager start filesystem

跟踪服务器日志：

mcp-manager logs -f filesystem

更新所有服务器镜像：

mcp-manager update --all

网关使用

以进程模式启动网关（推荐，已充分测试）：

mcp-manager gateway --mode process --port 52080

以容器模式启动网关（用于Docker隔离）：

mcp-manager gateway --mode container --port 52080

测试网关健康状况：

curl http://localhost:52080/health

列出可用服务器：

curl http://localhost:52080/servers

发送MCP请求：

curl -X POST http://localhost:52080/mcp \
  -H "X-MCP-Server: filesystem" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"client","version":"1.0.0"}}}'

模式对比：

处理模式以本地进程的形式启动MCP服务器。已使用npm包进行全面测试。推荐用于开发。
集装箱模式作为Docker容器生成MCP服务器。提供隔离和资源限制。需要MCP服务器的Docker镜像。

克劳德代码集成

使用Claude代码注册mcp-manager及所有已启用的服务器：

mcp-manager register --config mcp-config.yaml

这将会：

注册 mcp-manager 它本身作为一个stdio MCP服务器运行 mcp-manager serve
通过网关将每个启用的服务器注册为HTTP端点（例如。， http://localhost:52080/mcp/filesystem)
更新 ~/.claude.json 对于当前项目

验证注册：

cat ~/.claude.json | jq '.projects["/path/to/your/project"].mcpServers'

取消注册所有内容：

mcp-manager unregister

其工作原理：

mcp-manager serve 启动网关并暴露管理工具（list_servers， server_status， gateway_status)
单个服务器（文件系统、Git 等）通过网关上的 HTTP 端点进行访问
每个服务器都维护自己的命名空间，并且可以在Claude代码中通过名称进行引用

配置

配置文件定义了所有MCP服务器及其设置。请参阅 examples/mcp-config.yaml 以一个完整示例来看。

配置位置

mcp-manager 按以下顺序搜索配置文件：

指定的路径为 -c 旗帜
./mcp-config.yaml
./.mcp-manager/config.yaml
~/.mcp-manager/config.yaml

配置结构

version: "1.0"

settings:
  data_dir: ~/.mcp-manager       # Runtime data directory
  network: mcp-network            # Docker network name
  log_level: info                 # Log level: debug, info, warn, error

servers:
  - name: server-name             # Unique server identifier
    enabled: true                 # Whether this server should be managed
    description: "Description"    # Human-readable description

    docker:
      image: org/image:tag        # Docker image to use
      pull_policy: if-not-present # always, never, if-not-present

    http_path: /mcp               # Optional: HTTP path for containers with HTTP endpoints
                                   # Appended to registration URL for Claude Code
                                   # Example: http://localhost:52080/mcp/server-name/mcp

    command: ["executable"]       # Command to run
    args: ["--flag", "value"]     # Command arguments

    env:                          # Environment variables
      - name: VAR_NAME
        value: "value"
      - name: VAR_FROM_ENV
        value_from_env: HOST_VAR  # Pass through from host

    volumes:                      # Volume mounts
      - host_path: /host/path
        container_path: /container/path
        read_only: false

    health_check:                 # Health check configuration
      enabled: true
      interval: 30s
      timeout: 10s
      retries: 3

    agents:                       # Agents to register with
      - claude-code

建筑学

组件

CLI（Command Line Interface）即命令行界面 (cmd/mcp-manager): 面向用户的命令行界面
配置 (internal/config): 配置加载和解析
Docker (internal/docker): Docker 容器管理
服务器 (internal/server): MCP服务器生命周期管理
网关 (internal/gateway): HTTP到标准输入输出协议网关
- 会话管理及超时清理
- 进程和容器的创建（或启动）
- JSON-RPC 2.0 消息处理
克劳德·科德 (internal/claudecode): 克劳德代码配置管理

网关架构

HTTP Client
    ↓
Gateway (persistent)
    ↓
Server Manager
    ↓
Persistent Server Instances (one per server name)
    ↓
stdio communication (JSON-RPC)
    ↓
Tool execution

容器生命周期：

网关在其运行期间会维护持久化的服务器实例（每个服务器名称对应一个实例）：

初创公司清理之前运行中产生的任何过期容器
首次请求为请求的服务器（例如，“filesystem”）生成容器
后续请求重用现有容器
关机退出时正确清理所有容器

清理场景：

正常关机从Claude Code关闭标准输入触发清理操作
信号关闭优雅地捕获并处理 SIGTERM/SIGINT 信号
错误关机上下文取消触发清理操作
下一个初创公司安全网清理工作会移除任何遗漏的容器

所有容器均贴有标签 managed-by=mcp-manager 以便轻松识别。

部署流程

直接集装箱模式

加载配置文件
如需创建Docker网络
对于每个已启用的服务器：
- （如需）拉取镜像
- 使用指定配置启动容器
- 监控容器状态

网关模式

启动HTTP网关服务器
根据客户要求：
- 创建具有唯一ID的会话
- 启动MCP服务器（进程或容器）
- 通过标准输入输出转发 JSON-RPC 消息
- 管理会话生命周期（默认30分钟超时）

克劳德代码集成

加载mcp-manager配置
将 mcp-manager 注册为运行的标准输入输出（stdio）服务器 mcp-manager serve
通过网关将每个启用的服务器注册为HTTP端点
更新 ~/.claude.json 每个项目服务器注册
重启后，Claude Code 中的服务器将可用

注册详情：

mcp-manager → stdio 服务器（提供管理工具）
每个MCP服务器 → HTTP终端点位于 http://localhost:{gateway_port}/mcp/{server-name}
网关端口默认为52080（可在设置中配置gateway_port）

路线图

已完成 ✅

[x] 基本项目结构
[x] 配置文件格式
[x] CLI（命令行界面）命令结构
[x] Docker 容器管理
[x] HTTP到标准输入输出网关（进程模式）
[x] HTTP转stdio网关（使用Docker附加的容器模式）
[x] JSON-RPC 2.0 协议处理
[x] 服务器实例管理（每个服务器持久化）
[x] 容器生命周期管理，支持优雅关闭
[x] 信号处理（SIGTERM，SIGINT）用于清理工作
[x] 启动时清理陈旧容器
[x] Claude 代码集成（注册/注销）
[x] 环境变量处理
[x] 卷挂载配置
[x] 全面的测试套件

进行中 🚧

[ ] 生产日志和指标

计划中📋

[ ] 持久化容器的健康监控
[ ] 网关对SSE流的支持
[ ] 连接池和优化
[ ] 支持额外的代理（Cursor 等）
[ ] 服务器管理的Web用户界面
[ ] 自动更新并检查版本
[ ] 服务器状态持久化

文档

全面的文档资料可在 docs/ 目录：

发布与分发

发布流程 - 完整指南：使用GitHub Actions CI/CD发布新版本及自动化更新Homebrew插件
Homebrew Tap 配置 - 关于设置和维护Homebrew tap仓库的详细指南

实施

实施概要 - 所有开发阶段的完整实施历史，包括：
- 用于HTTP到stdio桥接的网关实现
- Claude代码集成与注册
- 带有附加API的Docker容器模式
- 容器生命周期管理和清理
- 架构图和技术细节

测试

测试结果 - 全面的测试套件结果，包括单元测试、集成测试和手动测试
网关测试结果 - 流程模式网关功能的详细测试结果
集装箱模式测试结果 - 带流解复用的Docker容器模式测试结果

项目配置

CLAUDE.md（文件名或标题，可译为“克劳德文档”或保持原样，具体根据上下文确定是否需要翻译文件名） - 使用Claude Code和Serena MCP以增强开发协助的指南
塞雷娜工具指南 - 全面指南：有效使用Serena MCP语义代码工具

做出贡献

欢迎贡献！请随时提交拉取请求。

许可证

功能源代码许可证，第1.1版，MIT未来许可证（FSL-1.1-MIT）

见许可证详情请参阅文件。

摘要这是一个开源可用的许可协议，两年后将转换为MIT许可协议。您可以使用、修改和重新分发此软件，但仅限于非生产用途。如需超出本许可协议条款范围的生产用途，请联系许可方。

致谢

设计用于与……协同工作模型上下文协议并且克劳德·科德。

使用说明

MCP 管理员（或 MCP 管理系统）

概述

stdio服务器问题

特点/功能

安装

Homebrew（适用于 macOS 和 Linux）

下载二进制文件

来自源（或“来源”）

先决条件

快速入门

使用方法

命令

容器管理

网关

克劳德代码集成

全球旗帜

示例

集装箱管理

网关使用

克劳德代码集成

配置

配置位置

配置结构

建筑学

组件

网关架构

部署流程

直接集装箱模式

网关模式

克劳德代码集成

路线图

已完成 ✅

进行中 🚧

计划中📋

文档

发布与分发

实施

测试

项目配置

做出贡献

许可证

致谢

相关 MCP

微博数据服务

Ionic开发工具服务器

PostgreSQL双传输服务器

Context7 文档检索服务

学校门户数据CLI工具

等待功能服务器