AI导哈

MCP服务器管理工具

一个通过YAML文件管理Claude Desktop的MCP服务器配置的CLI工具，支持从市场浏览和安装服务器。

  • by flug
  • Go
  • 本地部署
  • 更新于
在 GitHub 查看 flug/mcp-compose

使用说明

MCP Compose

一个通过YAML文件管理Claude Desktop中MCP（模型上下文协议）服务器配置的命令行界面（CLI）工具。

⚠️ 实验性功能 - 请谨慎使用

这个工具正处于积极开发中，应被视为实验性质。虽然它包含了安全功能和验证机制，但请：

  • 备份您的Claude配置 在使用此工具之前
  • 先在非关键项目上进行测试
  • 在GitHub上报告任何问题
  • 该工具进行修改 ~/.claude.json 或平台特定的Claude Desktop配置文件

始终备份您的配置文件！

安装

go install github.com/flug/mcp-compose@latest

或者从源代码构建：

git clone https://github.com/flug/mcp-compose
cd mcp-compose
go build

快速入门

  1. 初始化 mcp-compose：

    mcp-compose init

    这将检测您的平台，定位您的Claude Desktop配置，并设置mcp-compose。

  2. 从市场中浏览并安装MCP服务器：

    # Interactive browsing with checkboxes (recommended!)
mcp-compose marketplace list
# 1. Browse 448+ servers from https://github.com/modelcontextprotocol/servers
# 2. Use arrow keys to navigate, space to select servers
# 3. Press enter, then provide your project path
# 4. Selected servers will be installed automatically

# Search for specific servers
mcp-compose marketplace search filesystem

# Install a single server directly
mcp-compose marketplace install filesystem /path/to/your/project

  3. 或者通过YAML管理服务器：

    # Export your current MCP servers
mcp-compose dump > mcp-servers.yaml

# Edit the YAML file
vim mcp-servers.yaml

# Apply changes
mcp-compose apply mcp-servers.yaml

用法

初始化命令

初始化mcp-compose配置。此操作将检测您的操作系统、用户以及Claude Desktop的配置路径。

mcp-compose init

`init` 命令：

  • 检测您的平台（Windows、macOS 或 Linux）
  • 找到您的Claude桌面配置文件
  • 创建 mcp-compose 配置文件
  • 显示系统信息

特定于平台的路径：

  • Linux： ~/.config/Claude/claude_desktop_config.json 或者 ~/.claude.json
  • macOS（苹果电脑操作系统）： ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows： %APPDATA%\Claude\claude_desktop_config.json

转储命令

从Claude Desktop配置中提取MCP服务器并以YAML格式输出：

mcp-compose dump

保存到文件：

mcp-compose dump > mcp-config.yaml

应用命令

更新 ~/.claude.json 从YAML文件中加载MCP服务器：

mcp-compose apply mcp-config.yaml

转换命令

将JSON格式的MCP服务器配置转换为YAML格式，进行验证，并可选择性地将其应用到 ~/.claude.json：

mcp-compose convert server.json /path/to/project

`convert` 命令支持两种 JSON 格式：

  1. 单服务器格式：
{
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
  "env": {
    "DEBUG": "true"
  },
  "scope": "project"
}
  1. 多个服务器（mcpServers 映射）：
{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"]
    },
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_example"
      }
    }
  }
}

该命令将：

  1. 验证JSON配置
  2. 将其转换为YAML格式
  3. 显示转换后的配置
  4. 询问你是否想将其应用于 ~/.claude.json

删除命令

从YAML配置文件中删除一个MCP服务器，并可选择性地从（其他位置）删除 ~/.claude.json：

mcp-compose delete mcp-config.yaml server-name /path/to/project

示例：

mcp-compose delete mcp-config.yaml filesystem /home/user/workspace/my-project

该命令将：

  1. 显示待删除的服务器配置
  2. 询问是否要从（某处）删除它 ~/.claude.json （如果它在那里存在的话）
  3. 在从YAML文件中删除前，请先确认
  4. 从YAML文件中移除服务器
  5. 可选择地将其从（某处）移除 ~/.claude.json

市场命令（或市场平台指令）

市场命令允许您浏览并从官方安装MCP服务器 模型上下文协议服务器存储库。

市场列表

通过交互式界面浏览并从市场安装MCP服务器：

mcp-compose marketplace list

这个命令将会：

  • 从 https://github.com/modelcontextprotocol/servers 获取最新的MCP服务器列表（448+台服务器）
  • 将结果缓存到本地以加快后续访问速度
  • 显示一个 带有复选框的交互式TUI（终端用户界面）
  • 允许您使用空格键选择多个服务器
  • 选择后询问您的项目路径
  • 将所有选定的服务器一次性安装到您的项目中

交互式控件：

  • 使用 箭头键 浏览服务器列表
  • 按压 空间 选择/取消选择一个服务器
  • 新闻界；媒体 右箭头 选择全部
  • 新闻界；媒体 左箭头 取消选择全部
  • 开始 打字 按名称或描述筛选服务器
  • 新闻界（或“媒体”） 进入 确认选择
  • 请输入您的 项目路径 当被提示时
  • 所选服务器将自动安装

这是发现和安装MCP服务器的推荐方法！

市场搜索

按名称或描述搜索MCP服务器：

mcp-compose marketplace search <query>

示例：

# Search for filesystem-related servers
mcp-compose marketplace search filesystem

# Search for Git-related servers
mcp-compose marketplace search git

# Search for database servers
mcp-compose marketplace search database

搜索不区分大小写，并且可以匹配服务器名称和描述。

市场安装

从市场安装MCP服务器：

mcp-compose marketplace install <server-name> <project-path>

示例：

mcp-compose marketplace install filesystem /home/user/workspace/my-project

安装命令将会：

  1. 在市场中搜索该服务器
  2. 显示服务器信息及安装详情
  3. 生成MCP服务器配置
  4. 在应用更改前请确认
  5. 在您的Claude Desktop配置中为指定项目添加服务器

注： 您可能需要重启 Claude 桌面应用以使更改生效。

YAML 配置格式

配置按项目路径组织。每个项目可以拥有自己的MCP服务器。

projects:
  /path/to/project:
    mcpServers:
      server-name:
        type: "stdio"      # or "http"
        command: "command-to-run"
        args:
          - "arg1"
          - "arg2"
        env:
          ENV_VAR: "value"
        scope: "project"   # optional: "local", "user", or "project"

      http-server-name:
        type: "http"
        url: "https://api.example.com/mcp"
        headers:
          Authorization: "Bearer token"

示例

projects:
  /home/user/workspace/my-project:
    mcpServers:
      filesystem:
        type: stdio
        command: npx
        args:
          - "-y"
          - "@modelcontextprotocol/server-filesystem"
          - "/path/to/allowed/directory"

      github:
        type: stdio
        command: npx
        args:
          - "-y"
          - "@modelcontextprotocol/server-github"
        env:
          GITHUB_TOKEN: "your-token-here"

      custom-api:
        type: http
        url: "https://api.example.com/mcp"
        headers:
          Authorization: "Bearer your-token"

工作流程

从市场安装

选项1：交互式浏览（推荐）

  1. 启动交互式市场浏览器：

    mcp-compose marketplace list

  2. 使用交互式文本用户界面（TUI）：

    • 浏览官方MCP仓库中的448+个服务器
    • 使用箭头键导航
    • 使用空格键选择多个服务器
    • 通过输入文字进行筛选
    • 按回车键确认选择

  3. 当提示时，输入您的项目路径

  4. 重启 Claude 桌面应用以应用更改

选项2：直接安装

  1. 搜索可用服务器：

    mcp-compose marketplace search <query>

  2. 安装所需的服务器：

    mcp-compose marketplace install <server-name> /path/to/your/project

  3. 重启Claude桌面版以应用更改

管理现有配置

  1. 导出当前配置：

    mcp-compose dump > mcp-config.yaml

  2. 使用您喜欢的编辑器编辑YAML文件

  3. 应用更改：

    mcp-compose apply mcp-config.yaml

从JSON中添加新的MCP服务器

  1. 获取或创建一个用于您的MCP服务器的JSON配置文件

  2. 转换并验证：

    mcp-compose convert server.json /path/to/your/project

  3. 检查转换后的YAML文件并确认应用

移除MCP服务器

  1. 如果您没有YAML文件，请导出当前配置：

    mcp-compose dump > mcp-config.yaml

  2. 删除服务器：

    mcp-compose delete mcp-config.yaml server-name /path/to/project

  3. 可选地确认从（某处）删除 ~/.claude.json

项目结构

mcp-compose/
├── main.go              # CLI entry point
├── pkg/
│   ├── models/          # Data structures
│   │   └── types.go
│   ├── config/          # Config file operations
│   │   └── config.go
│   └── commands/        # CLI commands
│       ├── dump.go      # Dump command
│       ├── apply.go     # Apply command
│       ├── convert.go   # Convert command
│       ├── delete.go    # Delete command
│       └── validate.go  # Validation logic

发展

构建：

go build

运行：

go run main.go dump
go run main.go apply config.yaml
go run main.go convert server.json /path/to/project
go run main.go delete config.yaml server-name /path/to/project

测试：

go test ./...

配置字段

MCP服务器类型

  • **stdio（在中文中通常不直接翻译，可理解为“标准输入输出”相关的库或函数集合，但具体翻译可能因上下文而异）**基于命令的MCP服务器（需要 command，可选 args 和 env)
  • **http（超文本传输协议）**基于HTTP的MCP服务器（需要 url，可选 headers)

范围值

  • 当地的；本地的服务器位于当前机器上
  • 用户服务器当前用户可用
  • 项目服务器特定于该项目

注释

安全特性

  • 该工具保留Claude配置中的所有其他字段，仅修改 mcpServers 每个项目的部分
  • 交互式提示防止意外修改
  • 在应用更改之前验证配置
  • 首次使用前需执行初始化命令

最佳实践

  • 始终备份您的配置 在做出更改之前：
    # Linux/macOS
cp ~/.claude.json ~/.claude.json.backup
# or if using standard location
cp ~/.config/Claude/claude_desktop_config.json ~/.config/Claude/claude_desktop_config.json.backup

# Windows (PowerShell)
Copy-Item "$env:APPDATA\Claude\claude_desktop_config.json" "$env:APPDATA\Claude\claude_desktop_config.json.backup"
  • 首先在非关键项目上测试更改
  • 使用 dump 在更改之前导出当前配置
  • 审查YAML输出结果 convert 在确认之前

技术细节

  • 在Claude Desktop中，MCP服务器按项目进行组织
  • 两者都 stdio 和 http 支持MCP类型服务器
  • 配置存储在用户的主目录中，而非与二进制文件一起存储
  • 多平台支持：Windows、macOS、Linux

相关 MCP