MCP配置管理器
项目介绍
# MCP 配置管理器
跨平台工具，用于管理在 Claude、Gemini、Codex 和其他AI系统中的模型上下文协议（MCP）服务器配置。
**基于经过实战考验的 `mcp_toggle.py` 脚本，并增强了架构和图形用户界面。**
## 🎉 项目状态
### ✅ 图形界面完全可用！
图形界面已完成并运行良好，所有主要功能均可操作。应用程序提供了一种现代且易于使用的管理MCP服务器的方式，无需接触JSON文件。
## 🚀 当前功能
### ✅ 完全实现
- **🖥️ 图形用户界面** - 使用PyQt6/tkinter的现代跨平台GUI
- **🎨 双图形后端** - PyQt6用于丰富的样式和提示，如果未安装PyQt6则自动回退到tkinter
- **📝 服务器配置编辑器** - 直接在GUI中编辑服务器配置
- **🔧 字段编辑系统** - 动态字段编辑，实时验证
- **🔍 项目发现** - 自动从项目.claude.json文件中发现MCP服务器
- **🗑️ 批量服务器删除** - 删除多个服务器时带有确认对话框
- **➕ 增强的服务器添加** - 添加服务器时具有改进的JSON验证和清理
- **💾 高级备份系统** - 在专用目录中组织备份，并与GUI集成
- **📦 快速备份与恢复** - 工具栏上的一键备份和恢复，带文件选择
- **🔄 服务器恢复** - 从备份文件中恢复服务器，包括已禁用的服务器
- **交互式CLI管理** - 具有完整功能的交互模式，用于服务器管理
- **多客户端支持** - 管理`.claude.json`、`.gemini/settings.json`和Codex配置文件
- **服务器启用/禁用** - 切换服务器的开启/关闭状态而不丢失配置
- **主复选框** - 一次批量选择或取消选择所有服务器
- **配置同步** - 在Claude、Gemini和Codex之间同步服务器
- **自动备份** - 在进行任何更改之前创建时间戳备份
- **预设管理** - 保存和加载特定项目的配置
- **快速预设模式** - 最小化、Web开发、全栈和测试预设
- **JSON服务器添加** - 通过粘贴JSON配置添加新服务器
- **跨平台支持** - 支持Windows、macOS和Linux
- **命令行接口** - 具有单独命令的完整CLI
- **配置验证** - 验证配置文件结构
- **视觉状态指示器** - 清晰的启用/禁用状态颜色
- **键盘快捷键** - 专业键盘导航（Ctrl+S保存，Esc取消）
- **视觉润色** - 蓝色的选择高亮，橙色的未保存指示，红色的验证错误
### 🚧 下一步功能（规划阶段）
- **健康监控** - 实时服务器连接状态
- **高级导入/导出** - 在机器之间导入/导出预设和配置
## 🚀 快速安装（推荐）
**一键安装：**
```bash
curl -fsSL https://raw.githubusercontent.com/holstein13/mcp-config-manager/master/install.sh | bash
安装程序将：
- ✅ 自动检查系统要求
- 📁 询问安装位置（带有智能默认值）
- 🐍 设置隔离的Python环境
- 🔗 将
mcp命令添加到PATH - 🖥️ 创建桌面快捷方式（Linux）
- 🗑️ 提供简单的卸载选项
安装后快速启动
# 启动GUI（推荐）
mcp gui
# 或使用别名
mcp-gui
# 交互式CLI模式
mcp interactive
# 检查状态
mcp status
# 显示所有选项
mcp --help
# 简单卸载
mcp uninstall
📦 手动安装
<details> <summary>点击展开手动安装步骤</summary>先决条件
- Python 3.8或更高版本
- 安装了Claude Code CLI、Gemini CLI和/或Codex
- PyQt6（可选但推荐）：提供丰富的样式、提示和更好的用户体验
- 如果未安装，应用会自动回退到tkinter（内置在Python中）
- 安装方法：
pip install PyQt6
克隆并安装
git clone https://github.com/holstein13/mcp-config-manager.git
cd mcp-config-manager
pip install -e .
# 可选：安装PyQt6以获得更好的GUI体验
pip install PyQt6
开发设置
# 设置开发环境
python -m venv venv
source venv/bin/activate # 在Windows上：venv\Scripts\activate
pip install -r requirements-dev.txt
pip install -e .
# 运行测试
pytest
🚀 使用
GUI模式（全新！推荐）
启动图形界面：
mcp-config-manager gui
macOS：创建本地的.app捆绑包
为了在macOS上更方便地启动，你可以创建一个可以双击、添加到Dock或通过Spotlight启动的本地.app捆绑包。
初始设置（一次性）
由于macOS的外部管理Python环境（PEP 668），你需要使用虚拟环境：
# 创建虚拟环境
python3 -m venv venv
# 激活虚拟环境
source venv/bin/activate
# 安装构建依赖项
pip install py2app
# 以可编辑模式安装应用
pip install -e .
# 安装PyQt6以支持GUI（如果尚未安装）
pip install PyQt6
构建.app捆绑包
# 激活虚拟环境（如果尚未激活）
source venv/bin/activate
# 构建.app捆绑包（从项目根目录）
./build_app.sh
# 或手动：
python3 scripts/build/setup_app.py py2app --dist-dir artifacts/dist
# 安装到Applications文件夹
cp -r "artifacts/dist/MCP Config Manager.app" /Applications/
该应用将被创建在artifacts/dist/MCP Config Manager.app。然后你可以：
- 双击"MCP Config Manager.app"来启动
- 通过Spotlight（⌘ + 空格，输入"MCP Config Manager"）启动
- 将其添加到Dock以便快速访问
代码更改后的重新构建
# 激活虚拟环境
source venv/bin/activate
# 清除之前的构建工件
rm -rf build artifacts/dist
# 构建.app捆绑包
./build_app.sh
# 安装到Applications文件夹
cp -r "artifacts/dist/MCP Config Manager.app" /Applications/
故障排除
如果构建失败：
- 确保你在虚拟环境中（
source venv/bin/activate） - 检查所有依赖项是否已安装（
pip list） - 清除构建工件并再次尝试（
rm -rf build artifacts/dist）
如果应用启动时崩溃：
- 从终端运行以查看错误消息：
/Applications/MCP\ Config\ Manager.app/Contents/MacOS/MCP\ Config\ Manager
注意： .app捆绑包是完全自包含的，包含了Python和所有依赖项。一旦构建完成，它就可以独立于你的虚拟环境工作。
GUI提供了：
- 🖥️ 带复选框的可视服务器列表
- ☑ 主复选框用于批量操作（☐/☑/⊟状态）
- 📝 服务器详情编辑器 - 单击任何服务器以编辑其配置
- 🔧 动态字段编辑器 - 每个字段类型的智能编辑器：
- 文本字段用于字符串和命令
- 数字字段带有验证
- 布尔切换用于真/假值
- 数组编辑器用于列表管理
- 对象编辑器用于嵌套配置
- 🔍 项目发现：
- 发现按钮扫描项目.claude.json文件
- 自动找到项目中的MCP服务器
- 智能重复检测和合并
- 位置感知服务器管理（全局 vs 项目）
- ✅ 实时验证 - 对配置更改立即反馈
- 🎨 视觉反馈：
- 蓝色高亮显示所选服务器
- 橙色指示器表示未保存更改
- 红色边框表示验证错误
- 当没有选择服务器时提供空状态指导
- 💾 备份与恢复：
- 备份按钮创建时间戳备份
- 恢复按钮列出并恢复以前的备份
- 在进行任何更改之前自动备份
- 🔄 在Claude/Gemini/Codex/All模式之间切换
- 💾 带视觉反馈的保存按钮
- ➕ 通过JSON添加新服务器，增强验证
- 🗑️ 批量删除服务器时带有确认
- 💾 带GUI反馈的快速备份和恢复
- 📁 预设管理对话框
- ⌨️ 完整的键盘快捷键（Ctrl+S保存，Esc取消）
交互式CLI模式
启动命令行交互界面：
mcp-config-manager interactive
这提供了原始mcp_toggle.py脚本的完整界面，包括：
- ✅/❌ 视觉服务器状态
- 🔄 实时模式切换（Claude/Gemini/Codex/All）
- 📁 预设管理
- ➕ 通过粘贴JSON添加服务器
- 🎯 快速预设模式（最小化、Web开发等）
命令行使用
# 显示当前状态
mcp-config-manager status
# 启用/禁用特定服务器
mcp-config-manager enable server-name
mcp-config-manager disable server-name
# 批量操作
mcp-config-manager enable-all
mcp-config-manager disable-all
# 备份和恢复
mcp-config-manager backup # 创建时间戳备份
mcp-config-manager restore backup-file.json # 从备份恢复
# 服务器管理
mcp-config-manager add-server server-name config.json # 从文件添加服务器
mcp-config-manager delete-server server-name # 永久删除服务器
# 应用预设模式
mcp-config-manager preset minimal # 只有context7 + browsermcp
mcp-config-manager preset webdev # + playwright
mcp-config-manager preset fullstack # + supabase, clerk, railway
# 验证配置
mcp-config-manager validate ~/.claude.json
模式操作
该工具支持四种模式：
- 仅Claude (
--mode claude) - 仅管理.claude.json - 仅Gemini (
--mode gemini) - 仅管理.gemini/settings.json - 仅Codex (
--mode codex) - 仅管理Codex配置 - 全部（同步） (
--mode all) - 保持所有配置同步
🖼️ 截图
GUI界面
MCP配置管理器GUI显示带有视觉反馈的服务器配置编辑
交互模式
🔧 MCP配置管理器 - 交互模式
==================================================
📊 当前状态：
------------------------------
模式：🔄 所有CLI（同步）
✅ 激活的服务器（将运行）：
[1] context7
[2] browsermcp
[3] playwright
❌ 禁用的服务器（不会运行）：
[d1] supabase
[d2] clerk
📋 操作：
[1-N] 禁用激活的服务器
[d1-N] 启用禁用的服务器
[a] 启用所有
[n] 禁用所有
[m] 最小化（context7 + browsermcp）
[w] Web开发（+ playwright）
[+] ➕ 添加新的MCP服务器
[p] 📁 预设管理
[c] 🔄 更改CLI模式
[s] 保存并退出
[q] 不保存退出
操作：
🛠️ 开发
项目结构
src/mcp_config_manager/
├── core/
│ ├── config_manager.py # 主配置管理
│ ├── server_manager.py # 服务器启用/禁用逻辑
│ └── presets.py # 预设管理
├── parsers/
│ ├── claude_parser.py # Claude配置解析
│ ├── gemini_parser.py # Gemini配置解析
│ └── base_parser.py # 解析接口
├── utils/
│ ├── backup.py # 备份功能
│ ├── sync.py # 配置同步
│ └── file_utils.py # 文件路径工具
├── gui/ # GUI组件
│ ├── main_window.py # 主应用程序窗口
│ ├── controllers/ # GUI库桥梁
│ │ └── server_controller.py
│ ├── widgets/ # UI组件
│ │ ├── server_list.py
│ │ ├── server_details_panel.py
│ │ └── field_editors/ # 动态字段编辑器
│ │ ├── base.py
│ │ ├── text.py
│ │ ├── number.py
│ │ ├── boolean.py
│ │ ├── array.py
│ │ └── object.py
│ └── dialogs/ # 模态对话框
└── cli.py # 命令行接口
字段编辑系统
字段编辑系统提供了针对服务器配置字段的动态类型特定编辑器：
架构
- 基础编辑器 (
field_editors/base.py)：定义接口的抽象基类 - 类型特定编辑器：每种数据类型的专用编辑器
- 工厂模式：
FieldEditorFactory根据字段类型创建适当的编辑器 - 验证：实时验证并带有视觉反馈
支持的字段类型
- 文本编辑器 - 单行或多行文本字段用于字符串和命令
- 数字编辑器 - 带有最小/最大验证的整数/浮点字段
- 布尔编辑器 - 用于真/假值的复选框
- 数组编辑器 - 带有添加/删除/重新排序能力的列表管理
- 对象编辑器 - 嵌套对象编辑，带有键值对
视觉反馈
- 橙色边框 - 字段已被修改（未保存更改）
- 红色边框 - 验证错误，宽度2px
- 浅红色背景 - 额外的错误指示（#FFF5F5）
- 工具提示 - 错误信息悬停在无效字段上
使用示例
# ServerDetailsPanel自动创建适当的编辑器
field_editor = FieldEditorFactory.create_editor(
field_name="command",
field_value="npx @modelcontextprotocol/server-sqlite",
field_type="string",
parent=self
)
# 连接信号以跟踪更改
field_editor.value_changed.connect(self.on_field_changed)
field_editor.validation_error.connect(self.on_validation_error)
核心API函数
以下新函数已在最近的提交中添加：
ConfigManager (core/config_manager.py)
create_backup()- 创建时间戳备份并返回GUI兼容的结果add_server()- 添加服务器，接口由ServerController预期- 增强的错误处理 - 为GUI集成改进的错误报告
ServerManager (core/server_manager.py)
add_server_with_name()- 使用显式名称和配置添加服务器delete_server()- 从配置和存储中永久删除服务器update_server_config()- 更新现有服务器配置- 增强的模式支持 - 更好地处理'claude'、'gemini'、'codex'、'all'模式
Backup System (utils/backup.py)
backup_all_configs()- 在专用目录中创建组织良好的备份list_backups()- 按类型列出可用的备份文件restore_backup()- 从备份文件中恢复配置- 组织存储 - 备份现在存储在专用的
backups/目录中
GUI Controllers (gui/controllers/server_controller.py)
add_server()- 服务器添加的GUI集成delete_servers()- 批量删除并带有确认对话框- 增强的事件处理 - 更好的信号/槽管理以更新GUI
新对话组件
DeleteServersDialog- 批量删除并带有安全确认- 增强的
AddServerDialog- JSON验证和清理功能 BackupRestoreDialog- 备份和恢复操作的GUI
JSON处理增强
- JSON清理 - 在AddServerDialog中移除注释并修复畸形JSON
- 增强的验证 - 对无效JSON配置提供更好的错误报告
- 批处理 - 支持从单个JSON输入添加多个服务器
开发设置
# 克隆仓库
git clone https://github.com/holstein13/mcp-config-manager
cd mcp-config-manager