Claude MCP Config Switcher

Claude MCP Manager

一款适用于 macOS 的命令行工具，可为 Claude Desktop 应用定义、管理和切换不同的 mcpServers 配置集（配置档）。

目标

Claude 桌面应用会将其配置（包括 mcpServers 端点）存储在 ~/Library/Application Support/Claude/claude_desktop_config.json 这个 JSON 文件中。此工具可让你定义单个服务配置，并将它们归入命名配置档（例如“default”、“work”和“experimental”）。激活配置档后，工具会用该配置档中定义的服务更新 Claude 主配置文件里的 mcpServers 区块，并自动重启 Claude 以应用更改。通过分离服务定义并使用环境变量存储密钥（参见“工作原理”），你可以轻松共享服务配置或将配置档提交到版本控制系统，而不会泄露敏感凭据。

快速安装（推荐）

在 macOS 终端中运行以下命令：

curl -fsSL https://raw.githubusercontent.com/BLTGV/claude-mcp-manager/main/install.sh | sh

此命令会下载并执行安装脚本，该脚本负责检查依赖项、复制文件并设置命令行工具。

要求

• macOS： 该脚本依赖 macOS 专用路径和命令（pgrep、kill、open）。它无法在 Windows 或 Linux 上运行。
• jq： 该脚本使用 jq 处理 JSON。通过 Homebrew 安装：brew install jq。
• bash： 需要较新版本的 bash（>= 3.2）以支持正则表达式匹配（=~）等功能。macOS 自带的 bash 已足够。

安装

手动安装

1. 克隆仓库或下载源代码。
2. 在终端中导航到项目目录。
3. 将安装程序设为可执行：chmod +x install.sh
4. 运行安装程序：

   ./install.sh
   

   • 脚本会尝试安装到 /usr/local/lib/claude-mcp-manager，并在 /usr/local/bin 中创建符号链接。如果你没有写入权限，可能需要使用 sudo。
   • 如果 /usr/local 不可写，脚本会改用 $HOME/.local/lib 和 $HOME/.local/bin。
   • 如果所选的 bin 目录不在 $PATH 中，安装程序会通知你并提供添加该目录的说明。

工作原理

• 配置目录： 所有数据都存储在 ~/.config/claude/ 中。
• 服务目录： 单个服务定义以 .json 文件的形式存储在 ~/.config/claude/servers/ 中。
• 配置档目录： 配置档以 .json 文件的形式存储在 ~/.config/claude/profiles/ 中，其中包含服务名称列表。
  • 每个配置档文件的格式如下：{\"servers\": [\"server1_name\", \"server2_name\"]}
• 目标文件： 脚本会修改 Claude 官方配置文件中的 mcpServers 键：~/Library/Application Support/Claude/claude_desktop_config.json。
• 密钥（.env 文件）： 你可以将敏感值（例如 API 密钥）存储在 ~/.config/claude/.env 中。服务定义文件可以使用 {{ENV:YOUR_API_KEY}} 或 {{DOTENV:YOUR_API_KEY}} 之类的占位符引用这些值。激活配置档时，脚本会解析这些占位符。
• 跟踪（loaded 文件）： 脚本会在 ~/.config/claude/loaded 中记录当前激活配置档的名称。
• 备份（last.json）： 应用新配置档之前，脚本会将目标文件中当前的 mcpServers 区块保存到 ~/.config/claude/last.json，以便使用 last 命令轻松回滚。
• 首次运行： 安装成功后，安装程序会运行 claude-mcp-manager server list，确保创建配置目录。

用法

claude-mcp-manager <command | profile_name | option>

主要命令

• <profile_name>：激活指定的配置。读取配置中列出的服务定义，解析密钥，构建 mcpServers 块，在主配置中备份当前块，写入新块，然后重启 Claude。
• last：恢复上次激活配置前处于启用状态的 mcpServers 块（来自 last.json），然后重启 Claude。
• server <subcommand>：管理服务定义。运行 claude-mcp-manager server help 查看详情。
• profile <subcommand>：管理配置。运行 claude-mcp-manager profile help 查看详情。

服务子命令（claude-mcp-manager server ...）

• list：列出在 ~/.config/claude/servers/ 中找到的可用服务定义文件。
• show <name>：显示指定服务定义文件的 JSON 内容。
• add <name> --file <path>：通过复制 <path> 中的内容添加新的服务定义。
• add <name> --json '{\"key\":\"value\"}'：使用提供的 JSON 字符串添加新的服务定义。
• edit <name>：在 $EDITOR（或 vim/nano 等默认编辑器）中打开指定的服务定义文件。
• remove <name>：删除指定的服务定义文件（会提示确认）。
• extract [--profile <name>]：从主 Claude 配置中读取 mcpServers 块，并将每个服务另存为独立文件到 ~/.config/claude/servers/。也可创建或更新指定的配置 <name>，将提取的所有服务列入其中。

配置子命令（claude-mcp-manager profile ...）

• list：列出在 ~/.config/claude/profiles/ 中找到的可用配置文件。
• show <name>：列出指定配置文件中包含的服务名称，并指出相应的服务定义文件是否存在。
• create <name>：创建新的空配置文件。
• copy <src> <dest>：将现有配置文件复制为新名称。
• edit <name>：在 $EDITOR（或 vim/nano 等默认编辑器）中打开指定的配置文件，以便手动编辑服务列表。
• add <profile> <server...>：将一个或多个服务名称添加到指定配置的 "servers" 数组中。
• remove <profile> <server...>：从指定配置的 "servers" 数组中移除一个或多个服务名称。
• delete <name>：删除指定的配置文件（会提示确认）。

选项

• help, -h, --help：显示主帮助信息。
• version, -v：显示脚本版本。

致谢

本项目借助 claude-task-master 构建。这是由 Eyal Toledano（@eyaltoledano）和 Ralph Ecom（@RalphEcom）开发的 AI 驱动任务管理系统，用于定义、管理和实现上述功能。

Shell 补全（可选）

Bash 和 Zsh shell 支持 Tab 补全。

首先，确保已安装 claude-mcp-manager，且可通过 PATH 访问。

Bash

1. 安装 bash-completion@2： 如果尚未安装，请使用 Homebrew 安装最新的 Bash 补全系统：

   brew install bash-completion@2
   

2. 添加到 .bash_profile： 按照 brew info bash-completion@2 输出的说明，在 ~/.bash_profile（或 ~/.bashrc）中添加必要的行。通常如下所示：

   # 在 ~/.bash_profile 中添加以下行（或类似内容）
   export BASH_COMPLETION_COMPAT_DIR="$(brew --prefix)/etc/bash_completion.d"
   [[ -r "$(brew --prefix)/etc/profile.d/bash_completion.sh" ]] && . "$(brew --prefix)/etc/profile.d/bash_completion.sh"
   

3. 生成并安装脚本： 运行以下命令生成补全脚本，并将其放入正确的目录：

   # 确定补全目录
   COMPLETION_DIR="$(brew --prefix)/etc/bash_completion.d"
   # 确保目录存在
   mkdir -p "$COMPLETION_DIR"
   # 生成脚本
   claude-mcp-manager completion bash > "${COMPLETION_DIR}/claude-mcp-manager"
   

4. 重新加载 Shell： 打开新的终端窗口，或运行 source ~/.bash_profile。

Zsh

Zsh 内置了补全支持。

1. 确保已运行 compinit： 确保 ~/.zshrc 文件中包含 autoload -U compinit && compinit（通常位于文件开头或结尾附近）。
2. 选择补全目录： Zsh 补全文件通常存放在 $fpath 变量列出的目录中。常见的用户专用位置是 ~/.zsh/completion。如果该目录不存在，请创建：

   mkdir -p ~/.zsh/completion
   

3. 将目录添加到 fpath： 确保在调用 compinit 之前，将此目录添加到 ~/.zshrc 中的 Zsh 函数路径：

   # 在 ~/.zshrc 顶部附近添加
   fpath=(~/.zsh/completion $fpath)
   
   # ... 其他 zsh 配置 ...
   
   # 确保已加载 compinit
   autoload -U compinit && compinit
   

4. 生成并安装脚本： 运行以下命令生成补全脚本。请注意，文件名以下划线（_）开头：

   claude-mcp-manager completion zsh > ~/.zsh/completion/_claude-mcp-manager
   

5. 重新加载 Shell： 打开新的终端窗口，或运行 source ~/.zshrc。

安装后，你应该可以使用 Tab 补全命令、子命令、配置名称和服务名称。

卸载

运行以下命令即可卸载：

claude-mcp-manager uninstall

这将删除脚本和命令符号链接。执行前会要求确认。

若要同时删除配置目录（~/.config/claude），其中包含所有配置、服务定义、日志和 .env 文件（可能含有机密），请使用：

claude-mcp-manager uninstall --remove-config

警告： 删除配置目录后无法恢复，并且需要单独确认。