内容
# MCP 服务器切换脚本
一套用于在 Claude Code 中管理 MCP（模型上下文协议）服务器的综合脚本。这些脚本允许您轻松启用、禁用和管理 MCP 服务器，而不会丢失其配置。
## 🚀 功能
- **单个服务器管理**：启用/禁用特定 MCP 服务器
- **批量操作**：一次性启用/禁用所有服务器
- **完整配置保留**：保存具有所有参数、环境变量和正确 JSON 结构的完整服务器对象
- **目录感知配置**：自动检测并使用适当的配置文件（本地 `.claude.json`、`.mcp.json` 或用户 `~/.claude.json`）
- **增强的可视化显示**：带有 Unicode 符号和边框的漂亮彩色状态
- **动态 Raycast 下拉菜单**：自动填充的服务器选择菜单，自动更新
- **交互式选择**：编号菜单，方便服务器选择
- **多个 Raycast 接口**：文本输入、下拉菜单和交互式选项
- **状态监控**：查看活动和禁用的服务器，带有时间戳和源文件信息
- **环境变量支持**：安全处理 API 密钥、令牌和其他凭证
- **零配置损失**：永远不会丢失 MCP 服务器设置 - 保证完美恢复
## 📁 脚本概述
### 核心脚本
| 脚本 | 目的 | 用法 |
|--------|---------|--------|
| `toggle-mcp-server.sh` | **主要 CLI** - 增强状态显示，带有颜色/边框 | 终端操作 |
| `add-mcp-server.sh` | **添加新服务器** - 交互式服务器添加，带有验证 | 添加活动或非活动服务器 |
| `raycast-mcp-master.sh` | **统一 Raycast** - 所有操作在一个界面 | 服务器名称的文本输入 |
| `raycast-mcp-manager.py` | **状态显示** - 只读服务器查看器 | 状态监控 |
### 动态下拉脚本（新）
| 脚本 | 目的 | 用法 |
|--------|---------|--------|
| `raycast-disable-server.py` | **生成器** - 创建禁用下拉脚本 | 运行以更新禁用选项 |
| `raycast-enable-server.py` | **生成器** - 创建启用下拉脚本 | 运行以更新启用选项 |
| `raycast-disable-mcp-server.py` | **自动生成** - 禁用时使用下拉菜单 | Raycast 下拉选择 |
| `raycast-enable-mcp-server.py` | **自动生成** - 启用时使用下拉菜单 | Raycast 下拉选择 |
| `update-raycast-dropdowns.sh` | **便捷** - 更新两个生成器 | 刷新下拉菜单 |
### 交互式脚本
| 脚本 | 目的 | 用法 |
|--------|---------|--------|
| `raycast-mcp-dynamic.py` | **交互式** - 编号服务器选择 | 增强的用户体验，带有菜单 |
### 配置文件
| 文件 | 目的 |
|------|---------|
| `~/.claude.json` | Claude Code 配置（自动检测） |
| `~/.mcp-toggle-config.json` | 禁用服务器存储 |
## 🔧 安装
1. **克隆/下载** 脚本到您首选的目录（例如 `~/Scripts/MCP-Toggle/`）
2. **使其可执行**：
```bash
chmod +x ~/Scripts/MCP-Toggle/*.sh
```
3. **对于 Raycast 用户**：将 Raycast 脚本添加到您的 Raycast 脚本目录
## 📝 命令行用法
### 基本命令
```bash
# 显示所有服务器（活动和禁用）
./toggle-mcp-server.sh status
# 禁用特定服务器
./toggle-mcp-server.sh disable server-name
# 启用特定服务器
./toggle-mcp-server.sh enable server-name
# 禁用所有活动服务器
./toggle-mcp-server.sh disable-all
# 启用所有禁用服务器
./toggle-mcp-server.sh enable-all
# 列出仅禁用的服务器
./toggle-mcp-server.sh list-disabled
# 显示帮助
./toggle-mcp-server.sh help
```
### 示例
```bash
# 禁用 desktop-commander 服务器
./toggle-mcp-server.sh disable desktop-commander
# 检查哪些服务器是活动的
./toggle-mcp-server.sh status
# 重新启用 desktop-commander 服务器
./toggle-mcp-server.sh enable desktop-commander
# 禁用所有服务器以进行干净的 Claude 会话
./toggle-mcp-server.sh disable-all
# 恢复所有服务器
./toggle-mcp-server.sh enable-all
```
### 添加新服务器
使用交互式 `add-mcp-server.sh` 脚本添加新的 MCP 服务器：
```bash
# 运行交互式添加脚本
./add-mcp-server.sh
# 获取输入格式帮助
./add-mcp-server.sh --help
```
**关键点：**
- **不需要引号** - 直接输入值
- 服务器名称：使用小写字母和连字符（例如 `my-server`）
- 命令：输入可执行名称或完整路径
- 参数：每行一个，无需特殊格式化
- 环境变量：`KEY=value` 格式
- 选择启动活动或非活动
**示例流程：**
```
服务器名称：my-mcp-server
命令：npx
参数 0：@my/mcp-package
参数 1：--port=3000
参数 2：[按 Enter 键完成]
该服务器是否需要环境变量？n
是否启动服务器活动？n
```
## 🎯 Raycast 集成
### 可用的 Raycast 脚本
#### 传统界面
1. **`raycast-mcp-master.sh`** - *统一控制器*
- 操作：状态、禁用服务器、启用服务器、禁用所有、启用所有
- 需要手动输入服务器名称
- 颜色编码输出
2. **`raycast-mcp-manager.py`** - *状态显示*
- 操作：列出服务器、显示禁用
- 只读服务器查看器
- 清洁格式化输出
#### 动态下拉界面（新）
3. **`raycast-disable-mcp-server.py`** - *禁用时使用下拉菜单*
- 预先填充的活动服务器下拉菜单
- 无需输入 - 只需从列表中选择
- 自动从当前服务器状态生成
4. **`raycast-enable-mcp-server.py`** - *启用时使用下拉菜单*
- 预先填充的禁用服务器下拉菜单
- 从可用的禁用服务器中选择
- 自动从当前服务器状态生成
5. **`update-raycast-dropdowns.sh`** - *刷新下拉菜单*
- 更新两个下拉脚本，包含当前服务器列表
- 在更改服务器配置后运行
- 保持下拉选项更新
#### 交互界面
6. **`raycast-mcp-dynamic.py`** - *交互式选择*
- 编号服务器选择菜单
- 增强的用户体验
- 适用于喜欢引导式选择的用戶
### Raycast 设置
1. 将脚本复制到您的 Raycast 脚本目录
2. 脚本将自动出现在 Raycast 中，并带有适当的元数据
3. **对于下拉脚本**：首先运行 `update-raycast-dropdowns.sh` 以填充选项
4. **推荐的工作流程**：
- 使用下拉脚本进行日常服务器管理
- 在服务器配置更改时使用 `update-raycast-dropdowns.sh`
- 使用主脚本进行批量操作
## 🗂️ 工作原理
### 架构
```
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Raycast UI │───▶│ 主脚本 │───▶│ toggle-mcp- │
│ │ │ │ │ server.sh │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│
▼
┌─────────────────┐ ┌─────────────────┐
│ ~/.claude.json │◀───│ 配置管理 │
│ （活动） │ │ │
└─────────────────┘ └─────────────────┘
│
▼
┌─────────────────┐
│ ~/.mcp-toggle- │
│ config.json │
│ （禁用） │
└─────────────────┘
```
### 服务器状态
- **活动**：在 `~/.claude.json` 中列于 `mcpServers` 下
- **禁用**：移动到 `~/.mcp-toggle-config.json`，带有时间戳
- **配置**：保留命令、参数和元数据
### 文件结构
```
~/.claude.json # Claude Code 主配置文件
{
"mcpServers": {
"server-name": {
"type": "stdio",
"command": "command",
"args": ["arg1", "arg2"]
}
}
}
~/.mcp-toggle-config.json # 禁用服务器备份
{
"server-name": {
"command": "完整命令字符串",
"disabled_at": "2025-08-23T17:41:53Z"
}
}
```
## 🔧 技术改进（v3.0）
### 完整配置保留
与仅保存命令为连接字符串的早期版本不同，当前系统保留：
- 完整的服务器配置对象，包含所有字段
- `type` 字段（必需的 "stdio" 值）
- `command` 和 `args` 数组的正确分隔
- 环境变量，安全存储
- 源配置文件跟踪
### 目录感知配置检测
脚本自动检测并使用正确的 Claude 配置文件：
1. **本地 `.claude.json`** 在当前目录（项目特定）
2. **本地 `.mcp.json`** 文件用于项目配置
3. **用户 `~/.claude.json`** 作为后备（全局配置）
这确保脚本在您的主目录、项目文件夹或任何子目录中都能正确工作。
### 增强状态显示
- 显示正在使用的配置文件
- 指示带有环境变量的服务器 `[env]`
- 显示禁用的服务器的源文件，当与当前配置不同时
- 颜色编码输出，方便阅读
### 动态 Raycast 集成
- 生成器脚本根据当前服务器状态自动创建下拉菜单
- Raycast 脚本中不再需要硬编码的服务器列表
- 在启用/禁用操作后自动更新
- 在下拉选项中保持当前服务器状态
## 🎨 当前服务器库存
截至上次运行，您的设置包括：
### 活动服务器（17）
- `reddit` - Reddit API 集成
- `fastmail` - Fastmail 邮件管理
- `desktop-commander` - 桌面自动化
- `iterm-mcp` - iTerm 终端集成
- `browsermcp` - 浏览器自动化
- `apple-mcp` - Apple 服务集成
- `apple-reminders` - 提醒应用集成
- `notion` - Notion 工作区管理
- `peekaboo` - 屏幕捕捉和分析
- `paperless` - 文档管理
- `context7` - 文档上下文
- `mcp-reddit-companion` - 增强的 Reddit 功能
- `flights` - 飞行信息
- `mcp-obsidian` - Obsidian 保险库集成
- `youtube` - YouTube 数据访问
- `google-maps` - 地图和位置服务
- `hass-mcp` - Home Assistant 集成
## 🔍 故障排除
### 常见问题
**问：脚本显示“No MCP servers configured”**
- **答：** 检查 `~/.claude.json` 是否存在并包含 `mcpServers` 部分
**问：服务器无法禁用**
- **答：** 确保服务器名称与 `status` 中显示的名称完全匹配
**问：更改无效**
- **答：** 在进行更改后重启 Claude Code
**问：权限错误**
- **答：** 确保脚本可执行：`chmod +x *.sh`
### 调试步骤
1. **检查配置**：
```bash
cat ~/.claude.json | grep -A 10 mcpServers
```
2. **验证脚本权限**：
```bash
ls -la ~/Scripts/MCP-Toggle/*.sh
```
3. **测试状态命令**：
```bash
./toggle-mcp-server.sh status
```
## 🔧 高级用法
### 自定义工作流程
**开发模式**（最小服务器）：
```bash
# 禁用除必要服务器之外的所有服务器
./toggle-mcp-server.sh disable-all
./toggle-mcp-server.sh enable desktop-commander
./toggle-mcp-server.sh enable fastmail
```
**全功能模式**（所有服务器）：
```bash
./toggle-mcp-server.sh enable-all
```
**干净会话**（无 MCP 服务器）：
```bash
./toggle-mcp-server.sh disable-all
```
### 自动化
**添加到 .zshrc 以便快速访问**：
```bash
alias mcp-status='~/Scripts/MCP-Toggle/toggle-mcp-server.sh status'
alias mcp-disable-all='~/Scripts/MCP-Toggle/toggle-mcp-server.sh disable-all'
alias mcp-enable-all='~/Scripts/MCP-Toggle/toggle-mcp-server.sh enable-all'
```
## 📂 目录结构
```
~/Scripts/MCP-Toggle/
├── toggle-mcp-server.sh # 主要 CLI 脚本（增强的可视化效果）
├── add-mcp-server.sh # 交互式新服务器添加
├── raycast-mcp-master.sh # 统一 Raycast 控制器
├── raycast-mcp-manager.py # Python 状态查看器
├── raycast-mcp-dynamic.py # 交互式服务器选择
│
├── raycast-disable-server.py # 禁用下拉菜单生成器
├── raycast-enable-server.py # 启用下拉菜单生成器
├── raycast-disable-mcp-server.py # 自动生成的禁用脚本
├── raycast-enable-mcp-server.py # 自动生成的启用脚本
├── update-raycast-dropdowns.sh # 更新下拉菜单选项
│
├── raycast-update-mcp.sh # MCP 更新脚本（单独）
├── backup/ # 废弃脚本
│ ├── raycast-toggle-mcp.sh
│ └── raycast-toggle-mcp-wrapper.sh
└── README.md # 本文档
```
## 🚨 重要注意事项
- **始终备份**：您的 Claude 配置在更改前会自动备份
- **需要重启**：更改生效后需要重启 Claude Code
- **区分大小写**：服务器名称区分大小写
- **安全操作**：所有操作都保留原始服务器配置
- **无数据丢失**：禁用的服务器保留所有设置，可以完美恢复
## 📋 快速参考
| 想要... | 命令 | Raycast 替代方案 |
|------------|---------|-------------------|
| 查看所有服务器 | `./toggle-mcp-server.sh status` | "MCP 管理器" → 列出服务器 |
| **添加新服务器** | `./add-mcp-server.sh` | *仅限终端* |
| 禁用一个服务器 | `./toggle-mcp-server.sh disable SERVER_NAME` | **"禁用 MCP 服务器"** （下拉菜单） |
| 启用一个服务器 | `./toggle-mcp-server.sh enable SERVER_NAME` | **"启用 MCP 服务器"** （下拉菜单） |
| 禁用所有服务器 | `./toggle-mcp-server.sh disable-all` | "MCP 主控制器" → 禁用所有 |
| 启用所有服务器 | `./toggle-mcp-server.sh enable-all` | "MCP 主控制器" → 启用所有 |
| 更新下拉菜单 | `./update-raycast-dropdowns.sh` | **"更新 MCP Raycast 下拉菜单"** |
## 🆘 支持
如果您遇到问题：
1. 检查上述故障排除部分
2. 验证文件权限和路径
3. 确保 Claude Code 配置正确
4. 检查安装目录是否包含所有必需文件
---
**版本**：3.0
**最后更新**：2025 年 8 月 23 日
**兼容性**：Claude Code + macOS
**新功能**：增强的可视化显示、动态 Raycast 下拉菜单、交互式选择菜单
