使用说明

MCP经理

使用Docker管理模型上下文协议（MCP）服务器的基于shell的工具

MCP Manager通过Docker容器化简化了MCP服务器的部署和管理。它提供了一个统一的界面，用于在不同的AI开发环境中设置、配置和维护多个MCP服务器。

特性

🚀 轻松设置 -从源代码存储库中提取预构建映像或构建
🐳 基于Docker -隔离、可复制的服务器环境
🔧 多平台 -自动平台检测（amd64/arm64）
📝 配置生成 -为Claude Code、Claude Desktop、Gemini CLI生成配置
🔐 环境管理 -集中式 .env 机密文件
✅ 健康检查 -通过MCP协议测试验证服务器准备就绪
🧪 测试良好 -使用ShellSpec进行237+个单元测试

快速开始

先决条件

码头工人 （20.10+）-容器运行时
年（v4+）-YAML处理器
jq公司 （1.6+）-JSON处理器
版本控制系统 -从源头进行建设
jinja2-cli -模板渲染

安装：

# macOS
brew install docker yq jq git
pip install jinja2-cli

# Debian/Ubuntu
apt-get install docker.io jq git
sudo wget -qO /usr/local/bin/yq https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64
sudo chmod +x /usr/local/bin/yq
pip install jinja2-cli

安装

# Clone the repository
git clone https://github.com/Govinda-Fichtner/mcp-manager.git
cd mcp-manager

# Make script executable
chmod +x mcp_manager.sh

# Check dependencies
./mcp_manager.sh version

基本命令

# List available MCP servers
./mcp_manager.sh list

# Setup a server (pulls or builds Docker image)
./mcp_manager.sh setup github

# View server information
./mcp_manager.sh info github

# Check server health
./mcp_manager.sh health github

# Generate client configuration
./mcp_manager.sh config github --format claude-code

使用指南

可用命令

`list`

显示注册表中可用的所有MCP服务器及其类别和描述。

./mcp_manager.sh list

`setup <server>`

通过拉取预构建的Docker映像或从源代码库构建来设置MCP服务器。

# Pull from Docker registry (e.g., GitHub server)
./mcp_manager.sh setup github

# Build from Git repository (e.g., Obsidian server)
./mcp_manager.sh setup obsidian

`info <server>`

显示特定服务器的详细信息，包括源代码、环境变量和Docker配置。

./mcp_manager.sh info github

`health <server>`

通过检查Docker镜像是否存在和MCP协议合规性来验证服务器健康状况。

./mcp_manager.sh health github

`config <server>`

为Claude Code、Claude Desktop或Gemini CLI生成客户端配置。

# Full configuration file
./mcp_manager.sh config github --format claude-code --full

# Snippet for manual copy-paste
./mcp_manager.sh config github --format claude-code --snippet

# Single-line JSON for 'claude mcp add-json' command
./mcp_manager.sh config github --format claude-code --add-json

支持的格式：

claude-code -Claude代码JSON格式
claude-desktop -Claude桌面JSON格式
gemini-cli -Gemini CLI YAML格式

`version`

显示MCP管理器版本并检查依赖关系状态。

./mcp_manager.sh version

环境配置

创建一个 .env 用于存储凭据和路径的文件：

# Copy template
cp .env.example .env

# Edit with your credentials
nano .env

示例 .env 文件：

# GitHub MCP Server
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here

# Obsidian MCP Server
OBSIDIAN_API_KEY=your_api_key_here
OBSIDIAN_BASE_URL=https://127.0.0.1:27124
OBSIDIAN_VAULT_NAME=MyVault

# Filesystem MCP Server
ALLOWED_DIRECTORIES=/home/user/projects,/home/user/documents

# Debugger MCP Servers
DEBUGGER_WORKSPACE=/home/user/code

添加自定义服务器

更新注册表 (mcp_server_registry.yml):

servers:
  my-server:
    name: "My Custom MCP Server"
    description: "What this server does"
    category: "custom"
    server_type: "api_based"  # or "mount_based", "standalone"

    source:
      type: "registry"  # or "repository"
      image: "ghcr.io/org/my-server:latest"

    environment_variables:
      - "MY_API_KEY"
      - "MY_CONFIG_PATH"

    docker:
      network_mode: "host"

    startup_timeout: 10

添加凭据 (.env):

MY_API_KEY=your_key_here
MY_CONFIG_PATH=/path/to/config

测试:

./mcp_manager.sh info my-server
./mcp_manager.sh setup my-server
./mcp_manager.sh health my-server

故障排除

缺失依赖项

# Check which dependencies are missing
./mcp_manager.sh version

# Install missing tools (see Prerequisites)

YAML语法无效

确保你使用的是yq v4+（Go版本），而不是旧的Python版本：

yq --version  # Should show v4.x.x

拉取图像失败

# Check Docker daemon
docker info

# Verify registry URL in mcp_server_registry.yml
./mcp_manager.sh info <server>

# Test network connectivity
curl -I https://ghcr.io

无法从源构建

# Verify Git is installed
git --version

# Check repository is accessible
git ls-remote <repository-url>

# Check Docker build logs
docker images | grep mcp

服务器未启动

# Check Docker logs
docker ps -a | grep <server-name>
docker logs <container-id>

# Verify environment variables are set
cat .env | grep <VAR_NAME>

# Test health check manually
./mcp_manager.sh health <server> -v

权限不足

# Add user to docker group (Linux)
sudo usermod -aG docker $USER
newgrp docker

# Or use sudo
sudo ./mcp_manager.sh setup <server>

注册表参考

注册表架构

这 mcp_server_registry.yml 该文件使用结构化的YAML模式定义了所有可用的MCP服务器。

必填字段

字段	类型	描述	示例
`name`	string	人类可读的服务器名称	“GitHub MCP服务器”
`description`	string	服务器做什么	“GitHub API集成”
`category`	string	服务器类别	“开发”、“知识”
`server_type`	enum	服务器分类	“基于api”、“基于mount-based”、“独立”
`source.type`	enum	如何获取服务器	“注册表”或“存储库”

源配置

注册表类型 （提取预构建图像）：

source:
  type: "registry"
  image: "ghcr.io/org/server:latest"

存储库类型 （从源代码构建）：

source:
  type: "repository"
  repository: "https://github.com/org/repo.git"
  image: "local/server:latest"
  dockerfile: "Dockerfile"  # optional
  build_context: "."  # optional

可选字段

字段	类型	描述	示例
`environment_variables`	string[]	必需的env变量	[“API_KEY”，“BASE_URL”]
`volumes`	string[]	卷装规格	[“VAULT:/VAULT:ro”]
`docker.network_mode`	string	Docker网络模式	“主机”、“网桥”
`docker.cmd`	string[]	容器命令	[“node”，“index.js”]
`startup_timeout`	number	启动超时（秒）	10,30

服务器类型

`api_based`

需要API凭据，但不能访问本地文件。

例子： GitHub、Figma、Heroku服务器

github:
  server_type: "api_based"
  environment_variables:
    - "GITHUB_PERSONAL_ACCESS_TOKEN"
  docker:
    network_mode: "host"

`mount_based`

需要卷装载才能访问本地文件/目录。

例子： 文件系统、调试器、黑曜石服务器

filesystem:
  server_type: "mount_based"
  environment_variables:
    - "ALLOWED_DIRECTORIES"
  volumes:
    - "/project:/project:ro"

`standalone`

自给自足，没有外部依赖。

例子： 内存服务，基本实用程序

memory-service:
  server_type: "standalone"
  # No environment variables or volumes required

完整示例

示例1:GitHub（注册表拉取）

github:
  name: "GitHub MCP Server"
  description: "GitHub repository management, issues, pull requests, and code search"
  category: "development"
  server_type: "api_based"

  source:
    type: "registry"
    image: "ghcr.io/github/github-mcp-server:latest"

  environment_variables:
    - "GITHUB_PERSONAL_ACCESS_TOKEN"

  docker:
    network_mode: "host"

  startup_timeout: 10

示例2：黑曜石（存储库构建）

obsidian:
  name: "Obsidian MCP Server"
  description: "Comprehensive Obsidian vault management"
  category: "knowledge"
  server_type: "api_based"

  source:
    type: "repository"
    repository: "https://github.com/cyanheads/obsidian-mcp-server.git"
    image: "local/obsidian-mcp-server:latest"
    dockerfile: "support/docker/Dockerfile.obsidian"
    build_context: "."

  environment_variables:
    - "OBSIDIAN_API_KEY"
    - "OBSIDIAN_BASE_URL"
    - "OBSIDIAN_VAULT_NAME"

  docker:
    network_mode: "host"

  startup_timeout: 20

示例3：调试器（多语言）

debugger-python:
  name: "DAP MCP Server (Python)"
  description: "Debug Adapter Protocol server for Python debugging"
  category: "development"
  server_type: "mount_based"

  source:
    type: "repository"
    repository: "https://github.com/Govinda-Fichtner/debugger-mcp.git"
    image: "mcp-debugger-python:latest"
    dockerfile: "Dockerfile.python"
    build_context: "."

  environment_variables:
    - "DEBUGGER_WORKSPACE"

  volumes:
    - "DEBUGGER_WORKSPACE:/workspace"

  docker:
    network_mode: "host"
    cmd: ["debugger_mcp", "serve"]

  startup_timeout: 15

发展

项目结构

mcp-manager/
├── mcp_manager.sh           # Main script (~1,400 lines)
├── mcp_server_registry.yml  # Server definitions
├── .env.example             # Environment template
├── support/
│   ├── docker/              # Custom Dockerfiles
│   └── templates/           # Jinja2 config templates
└── spec/
    ├── unit/                # Unit tests (237 examples)
    └── fixtures/            # Test data

建筑

设计原则：

单脚本 -中的所有功能 mcp_manager.sh 为简单起见
无状态 -直接查询Docker，无状态文件损坏
基于模板 -Jinja2配置生成模板
经过充分测试 -具有模拟依赖关系的ShellSpec单元测试

关键部件：

注册表解析器 -使用yq进行服务器定义的YAML解析
Docker管理器 -图像提取、构建和健康检查
配置生成器 -面向多个客户端的Jinja2模板渲染
环境处理程序 -集中式 .env 文件管理

运行测试

# Install ShellSpec
curl -fsSL https://git.io/shellspec | sh -s -- --yes

# Run all unit tests
shellspec spec/unit/

# Run specific test file
shellspec spec/unit/health_command_spec.sh

# With verbose output
shellspec spec/unit/ --format documentation

贡献

我们欢迎捐款！请遵循以下指南：

叉和分支
```
git checkout -b feature/my-feature
```

先写测试 （TDD）

# Create test file
touch spec/unit/my_feature_spec.sh

# Write failing tests
shellspec spec/unit/my_feature_spec.sh  # Should fail

# Implement feature
nano mcp_manager.sh

# Tests should pass
shellspec spec/unit/my_feature_spec.sh

遵循代码样式
- 使用 shellcheck 对于linting
- 保持职能集中（单一职责）
- 为复杂逻辑添加注释
- 使用描述性变量名

运行质量检查

# Run all tests
shellspec

# Check shell script quality
shellcheck mcp_manager.sh

# Run pre-commit hooks
pre-commit run --all-files

承诺并推动

git add .
git commit -m "feat: add new feature"
git push origin feature/my-feature

创建拉取请求
- 描述发生了什么变化以及原因
- 参考任何相关问题
- 确保CI通过

CI/CD管道

GitHub Actions会在每次推送时自动运行：

ShellCheck -Lints shell脚本用于常见问题
外壳规格 -运行237个单元测试
YAML验证 -检查注册表语法
安全扫描 -检测硬编码的秘密

查看状态： GitHub操作

添加新服务器

看添加自定义服务器在使用指南中。

开发过程：

添加条目到 mcp_server_registry.yml
测试用 ./mcp_manager.sh info <server>
在中创建单元测试 spec/unit/servers/<server>_spec.sh
运行测试： shellspec spec/unit/servers/<server>_spec.sh
PR描述中的文件

许可证

MIT许可证-请参阅许可证文件以获取详细信息。

支持

问题: GitHub问题
讨论: GitHub讨论
MCP规范: https://modelcontextprotocol.io/

版本: 0.2.0 状态：积极发展