claude-mcp-switch - Claude Code MCP 切换器

一个零依赖的 npx 命令行工具，用于列出、启用和禁用 Claude Code MCP 服务器。 底层使用 claude 命令行工具以确保与实际运行配置的兼容性。

✨ 特性

• 列出活动和已禁用的 MCP 服务器（由 claude mcp list 提供支持）
• 按名称启用或禁用服务器
• 在禁用时保存服务器配置以便轻松重新启用
• 支持 JSON 输出和模拟模式
• 支持所有传输类型：stdio、SSE、HTTP
• 吸引人的用户界面：ASCII 标题、彩色输出和框绘表格
• 颜色控制：自动检测 TTY，通过 --no-color 或 NO_COLOR=1 禁用；在 --json 中始终关闭

📋 要求

• Node.js >= 18
• 已安装并配置了 Claude Code CLI (claude 命令可用)
• 在 Claude Code 中至少配置了一个 MCP 服务器

🚀 安装/使用

• 本地 npx 使用（无需安装）：

  1. 列出服务器：npx claude-mcp-switch list
  2. 启用服务器：npx claude-mcp-switch enable github
  3. 禁用服务器：npx claude-mcp-switch disable github --dry-run

• 通过 npm 全局安装：

  1. 全局安装：npm install -g claude-mcp-switch
  2. 使用工具：ccmcp list
  3. 启用 MCP：ccmcp enable github
  4. 禁用 MCP：ccmcp disable github

• 本地开发（无注册表）：

  1. 本地克隆仓库：
     • git clone <repo-url> 并 cd claude-mcp-switch
  2. 确保 CLI 入口点可执行：
     • macOS/Linux: chmod +x ./src/ccmcp.js （src/ccmcp.js 中存在 shebang）
  3. 全局链接以在任何地方使用 ccmcp 命令：
     • npm link （使用 package.json 中的 bin 映射）
  4. 使用工具：
     • ccmcp list
     • ccmcp enable github
     • 测试期间禁用颜色：ccmcp list --no-color
  5. 完成后取消链接：
  • npm unlink -g ccmcp （或在项目内运行 npm unlink）

• 替代方案：直接运行而不进行链接

  • macOS/Linux:
    • node ./src/ccmcp.js list
    • node ./src/ccmcp.js enable github --config ~/.claude/settings.json
  • Windows (CMD):
    • node .\src\ccmcp.js list
    • node .\src\ccmcp.js enable github --config %USERPROFILE%\.claude\settings.json
  • Windows (PowerShell):
    • node .\src\ccmcp.js list
    • node .\src\ccmcp.js enable github --config "$env:USERPROFILE\.claude\settings.json"

💻 命令

• list [--json] [--no-color]
  • 打印带有状态、名称、传输方式、命令/URL 的彩色框绘表格
  • 显示活动（来自 claude mcp list）和已禁用的服务器（来自本地存储）
• enable <name> [--dry-run] [--json] [--no-color]
  • 通过恢复其配置来重新启用先前已禁用的服务器
• disable <name> [--dry-run] [--json] [--no-color]
  • 通过移除服务器（使用 claude mcp remove）并存储其配置以便以后重新启用来禁用服务器
• --help, --version

🎯 工作原理

• 列出：执行 claude mcp list 获取活动服务器，并与本地存储的已禁用服务器合并
• 禁用：
  1. 通过 claude mcp get <name> 获取服务器详情
  2. 将配置存储在 ~/.claude-mcp-switch/disabled-servers.json
  3. 移除服务器（使用 claude mcp remove <name>）
• 启用：
  1. 从本地存储中检索存储的配置
  2. 使用原始设置通过 claude mcp add 重新添加服务器
  3. 从禁用存储中移除

🔍 配置

无需发现配置文件！该工具使用 claude CLI，后者会自动使用您的活动 Claude Code 配置。这确保了工具始终与您实际运行的 MCP 服务器一起工作。

🚪 退出码

• 0: 成功
• 2: 未找到服务器
• 4: 执行 claude CLI 命令时出错

📝 示例

• 列出所有服务器：

  npx claude-mcp-switch list
  

• 禁用一个服务器：

  npx claude-mcp-switch disable playwright
  

• 启用一个先前已禁用的服务器：

  npx claude-mcp-switch enable playwright
  

• 模拟模式：

  npx claude-mcp-switch disable playwright --dry-run
  

• JSON 输出：

  npx claude-mcp-switch list --json
  

📊 JSON 输出

• 列出：输出带有状态、名称、传输方式、commandOrUrl 的服务器对象数组
• 启用/禁用：输出 { ok, action, identifier, error? }

🔧 故障排除

• "claude: 命令未找到"：确保已安装 Claude Code CLI 并位于您的 PATH 中
• 未找到服务器：使用 claude mcp list 查看可用服务器，或使用 npx claude-mcp-switch list 查看活动和已禁用的服务器
• 权限错误：确保您对 ~/.claude-mcp-switch/ 目录具有写入权限

📚 参考

• Claude Code MCP: https://docs.claude.com/en/docs/claude-code/mcp
• Claude CLI 文档: https://docs.claude.com/en/docs/claude-code/cli

🧪 测试

该项目使用 Node.js 内置测试运行器（Node 18+），包括全面的单元和集成测试。

运行测试

# 运行所有测试
npm test

# 仅运行单元测试
npm run test:unit

# 仅运行集成测试
npm run test:integration

# 监视模式
npm run test:watch

# 覆盖报告
npm run test:coverage

测试覆盖

• 所有模块的单元测试（utils、config、schema、matcher、ui）
• CLI 命令的集成测试
• 使用临时配置文件的端到端测试
• 平台特定路径解析测试
• 错误处理和边缘情况覆盖

📄 许可证

MIT

🤖 GitHub 工作流

此项目包括全面的 CI/CD 自动化，具有多个 GitHub Actions 工作流。请参阅 CI/CD 工作流 以获取详细文档。