CC Switch MCP 服务器管理指南：统一配置 MCP 并一键同步到 Claude Code、Codex、Gemini 等 CLI 客户端

MCP（Model Context Protocol）服务器是连接 AI 编码工具与外部数据源、工具链的关键桥梁。本篇基于 CC Switch 用户手册中的 MCP Server Management 章节，结合仓库中 Rust 后端与前端预设的源码实现，完整讲解如何在 CC Switch 中通过预设模板或自定义配置添加 MCP 服务器、区分 stdio / http / sse 三种传输类型、控制 MCP 服务器向各客户端的启用开关，以及理解“数据库记录 + 实时配置投影”的同步机制与配置回写格式。读完后你可以独立完成：从添加、校验、应用绑定到编辑、删除、存量导入的全流程 MCP 管理。

1. MCP 是什么

MCP（Model Context Protocol）是一个允许 AI 工具访问外部数据源和工具的协议。通过 MCP 服务器，你可以让 AI：

• 访问文件系统
• 发起网络请求
• 查询数据库
• 调用外部 API

在 CC Switch 的定位中，MCP 管理是一个跨客户端的统一入口：你在 CC Switch 中维护一份 MCP 服务器清单，再按应用维度开关同步，由 CC Switch 负责把服务器配置投影（写入）到各 CLI 工具自己的配置文件里。

2. 打开 MCP 面板

点击顶部导航栏中的 MCP 按钮即可打开 MCP 管理面板。面板中集中展示所有已管理的 MCP 服务器，每行对应一个服务器，右侧提供应用启用开关、编辑与删除操作。

3. 添加 MCP 服务器

3.1 使用预设模板

添加步骤：

1. 点击右上角的 + 按钮
2. 在 "Preset"（预设）下拉框中选择一个模板
3. 按需修改配置
4. 点击 "Save" 保存

内置的常用预设如下：

Preset	包名	说明
fetch	mcp-server-fetch	使 AI 能抓取网页内容的 HTTP 请求工具
time	@modelcontextprotocol/server-time	提供当前时间信息的时间工具
memory	@modelcontextprotocol/server-memory	使 AI 能存取信息的记忆工具
sequential-thinking	@modelcontextprotocol/server-sequential-thinking	增强 AI 推理能力的思维链工具
context7	@upstash/context7-mcp	用于查询技术文档的文档搜索工具

从源码 src/config/mcpPresets.ts 可以看到，这 5 个预设全部以 stdio 类型定义：fetch 预设使用 uvx mcp-server-fetch，其余四个通过 npx -y <包名> 启动。值得注意的是 createNpxCommand 的跨平台处理：在 Windows 上会生成 cmd /c npx -y <包名> 的命令结构（因为 Windows 需要经由 cmd 执行 npx.cmd），而在 Mac/Linux 上则直接执行 npx。因此同一套预设无需用户手动调整即可跨平台工作。

3.2 自定义配置

在预设下拉框中选择 "Custom" 后，填写以下字段：

字段	是否必填	说明
Server ID	是	唯一标识符
Name	否	显示名称
Description	否	功能描述
Transport Type	是	stdio / http / sse
Command	是*	stdio 类型必填
Arguments	否	命令行参数
URL	是*	http / sse 类型必填
Headers	否	http / sse 类型的请求头
Environment Variables	否	传递给服务器的环境变量

3.3 保存时如何校验：源码级视角

保存前，后端会对服务器规范做一次严格的 schema 校验。src-tauri/src/mcp/validation.rs 中的 validate_server_spec 定义了全部规则：

• 服务器定义必须是 JSON 对象；
• type 只允许 stdio、http、sse 三种取值；省略 type 时默认按 stdio 处理（与社区常见的 .mcp.json 写法保持一致）;
• stdio 类型必须提供非空的 command 字段；
• http / sse 类型必须提供非空的 url 字段。

这与上表中的必填项（Command 对 stdio 必填、URL 对 http/sse 必填）一一对应，校验失败会返回明确的错误信息（例如 “stdio 类型的 MCP 服务器缺少 command 字段”），不会把非法配置写入任何客户端。

4. 三种传输类型详解

4.1 stdio（标准输入/输出）

最常用类型，通过启动一个本地进程进行通信。

{
  "command": "uvx",
  "args": ["mcp-server-fetch"],
  "env": {}
}

环境要求：

• 对应命令必须已安装（如 uvx、npx）
• 服务器程序必须位于 PATH 中

4.2 http

通过 HTTP 协议与远程服务器通信。

{
  "url": "http://localhost:8080/mcp"
}

4.3 sse（Server-Sent Events）

通过 SSE 协议与服务器通信，支持实时推送。

{
  "url": "http://localhost:8080/sse"
}

5. 应用绑定：每个服务器独立控制启用客户端

每个 MCP 服务器都可以独立控制它启用在哪些应用中。

5.1 各应用开关与配置文件路径

开关	效果	配置文件路径
Claude	同步到 Claude Code	~/.claude.json 的 mcpServers
Codex	同步到 Codex	~/.codex/config.toml 的 [mcp_servers]
Gemini	同步到 Gemini CLI	~/.gemini/settings.json 的 mcpServers
OpenCode	同步到 OpenCode	~/.config/opencode/opencode.json 的 mcp
Hermes	同步到 Hermes	~/.hermes/config.yaml 的 mcp_servers

注意：OpenClaw 和 Claude Desktop 目前不支持 CC Switch 的 MCP 同步。MCP 功能目前支持 Claude、Codex、Gemini、OpenCode 和 Hermes。

5.2 开关背后的同步机制

启用某个应用开关时，CC Switch 会依次做三件事：

1. 更新数据库：把该服务器 apps.claude/codex/gemini/opencode/hermes 中对应状态置为 true
2. 同步到实时配置：把服务器配置写入对应应用的配置文件
3. 立即生效：下次 CLI 工具启动时自动加载新的 MCP 服务器

禁用开关时则反向操作：数据库状态置为 false、从应用的配置文件中删除该服务器、下次 CLI 启动时不再加载。

这一流程在源码中的落点是 src-tauri/src/services/mcp.rs 的 McpService：

• toggle_app：先调用 update_mcp_server_app_enabled 更新数据库，再根据开关状态调用 sync_server_to_app（写入）或 remove_server_from_app（删除）；
• sync_server_to_app_no_config：按 AppType 分发到各客户端模块——Claude、Codex、Gemini、OpenCode、Hermes 各有独立的 mcp::sync_single_server_to_* 实现；AppType::OpenClaw 与 AppType::ClaudeDesktop 分支只写一条 debug 日志并跳过，与文档中“暂不支持同步”的说明完全吻合；
• upsert_server：编辑保存时还有一个容易忽略的细节——它会读取旧的应用启用集合，凡是“旧版本启用、新版本取消勾选”的应用，都会先从该应用的实时配置中移除服务器，再同步当前仍启用的应用。也就是说，编辑服务器时取消某个应用开关，等价于对该应用执行禁用。

此外，从源码结构看，src-tauri/src/mcp/ 模块中还包含一个 grokbuild.rs 同步/导入子模块（McpApps 结构体同样带有 grokbuild 字段，见 src-tauri/src/app_config.rs），说明后端已为 Grok Build 预留了 MCP 同步通道；但用户手册中面向用户的绑定表当前仅列出上述五个客户端。

5.3 同步的前置条件：应用必须已安装

MCP 同步只在对应应用已安装（有配置痕迹）时才会真正执行：

• Claude：需要 ~/.claude/ 目录或 ~/.claude.json 文件存在
• Codex：需要 ~/.codex/ 目录存在
• Gemini：需要 ~/.gemini/ 目录存在
• OpenCode：需要 ~/.config/opencode/ 目录存在
• Hermes：需要 ~/.hermes/ 目录存在

提示：如果某个 CLI 工具未安装，启用其开关不会报错，但配置不会被写入。

以 Claude 为例，should_sync_claude_mcp 的实现正是检查 ~/.claude 目录或 ~/.claude.json 是否存在，两者都不存在时直接跳过写入/删除，不会创建任何文件或目录——这就是“未安装时启用开关不报错、也不落盘”的实现依据。开关禁用时，配置则会被从文件中移除。

6. 编辑服务器

1. 点击服务器行右侧的 "Edit" 按钮
2. 修改配置
3. 点击 "Save" 保存

修改会立即同步到所有已启用应用的配置文件（对应上文 upsert_server 中的“处理禁用 + 全量同步启用应用”两步）。

7. 删除服务器

1. 点击服务器行右侧的 "Delete" 按钮
2. 确认删除

删除后，配置会从所有应用的配置文件中移除。源码层面见 delete_server：先删除数据库记录，再遍历该服务器当前启用的所有应用，逐一调用各客户端的 remove_server_from_* 清理实时配置。

8. 导入已有配置

如果你已经在各 CLI 工具中手工配置过 MCP 服务器，可以导入到 CC Switch 统一管理：

1. 点击 "Import" 按钮
2. 选择要导入来源的应用（Claude / Codex / Gemini / OpenCode / Hermes）
3. CC Switch 读取现有配置并完成导入

导入语义在源码中有明确约定（见 import_from_claude 等实现）：

• 导入是只读操作，只从各客户端的配置文件读取，不会反向写回任何应用的实时配置；
• 如果服务器 ID 已存在于 CC Switch 中，则只补上对应应用的启用位（例如从 Claude 导入时置 apps.claude = true），不覆盖已有字段与其他应用的启用状态；
• 真正的新服务器则以来源应用为默认唯一启用应用入库；
• 批量导入走 import_from_all_apps，采用 best-effort 策略：单个应用导入失败（比如某客户端配置是坏 JSON）不会阻断其余应用，失败信息会聚合成一条错误上报，而不是被静默吞掉表现为“导入成功 0 个”。

9. 各客户端的配置文件格式

同步落盘时，CC Switch 会按每个客户端自己的格式写入：

Claude（~/.claude.json）

{
  "mcpServers": {
    "mcp-fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
  }
}

Codex（~/.codex/config.toml）

Codex 使用 TOML 格式，mcpServers 映射为 [mcp_servers] 表：

[mcp_servers.mcp-fetch]
command = "uvx"
args = ["mcp-server-fetch"]

Gemini（~/.gemini/settings.json）

{
  "mcpServers": {
    "mcp-fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
  }
}

OpenCode 写入 ~/.config/opencode/opencode.json 的 mcp 字段、Hermes 写入 ~/.hermes/config.yaml 的 mcp_servers 字段，格式遵循各自客户端规范（对应实现分别在 src-tauri/src/mcp/opencode.rs 与 src-tauri/src/mcp/hermes.rs，其中 OpenCode 涉及 local/remote 两种服务器格式的转换）。

10. 常见问题（FAQ）

服务器无法启动

依次检查：

• 命令是否正确安装（如 uvx）
• 命令是否在 PATH 中
• 参数是否正确

配置不生效

确保：

• 对应应用的开关已启用
• CLI 工具已重启（新 MCP 服务器在下次 CLI 启动时才被加载）

11. 核心源码索引

关注点	源码位置
配置校验规则（stdio/http/sse）	src-tauri/src/mcp/validation.rs
统一服务器结构（id/name/server/apps/tags）	src-tauri/src/app_config.rs
增删改、开关切换、全量同步服务层	src-tauri/src/services/mcp.rs
各客户端同步/导入/移除子模块	src-tauri/src/mcp/mod.rs
Claude 同步前置条件检查	src-tauri/src/mcp/claude.rs
前端内置预设与跨平台 npx 处理	src/config/mcpPresets.ts
同步与导入的测试用例	src-tauri/tests/mcp_commands.rs、tests/hooks/useMcpBulkToggle.test.tsx

综上，CC Switch 的 MCP 管理可以概括为三层：统一存储（数据库中的 McpServer 记录 + 各应用启用位）→ 严格校验（保存与导入时统一过 validate_server_spec）→ 按需投影（按应用开关把配置以各客户端原生格式写入/移除其配置文件，未安装客户端时静默跳过）。掌握这一机制后，你就能在多个 AI 编码客户端之间复用同一套 MCP 服务器清单，而不必在每个工具里重复手工维护。