cc-switch/docs/user-manual/3-extensions/3.1-mcp.md

3.1 MCP 服务器管理

什么是 MCP

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

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

打开 MCP 面板

点击顶部导航栏的 MCP 按钮。

面板概览

添加 MCP 服务器

使用预设模板

1. 点击右上角 + 按钮
2. 在「预设」下拉框中选择模板
3. 根据需要修改配置
4. 点击「保存」

常用预设

预设	包名	功能说明
fetch	mcp-server-fetch	HTTP 请求工具，让 AI 能够获取网页内容
time	@modelcontextprotocol/server-time	时间工具，提供当前时间信息
memory	@modelcontextprotocol/server-memory	记忆工具，让 AI 能够存储和检索信息
sequential-thinking	@modelcontextprotocol/server-sequential-thinking	思维链工具，增强 AI 推理能力
context7	@upstash/context7-mcp	文档搜索工具，查询技术文档

自定义配置

选择「自定义」后，需要填写：

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

传输类型

stdio（标准输入输出）

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

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

要求：

• 需要安装对应的命令（如 uvx、npx）
• 服务器程序需要在 PATH 中

http

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

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

sse（Server-Sent Events）

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

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

应用绑定

每个 MCP 服务器可以独立控制启用的应用。

开关说明

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

开关实现机制

当开启某个应用的开关时，CC Switch 会：

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

当关闭某个应用的开关时，CC Switch 会：

1. 更新数据库：将对应应用状态设为 false
2. 从 Live 配置移除：从应用配置文件中删除该服务器
3. 即时生效：下次启动 CLI 工具时不再加载该 MCP 服务器

同步条件

MCP 服务器同步仅在对应应用已安装时执行：

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

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

关闭开关后，配置会从文件中移除。

编辑服务器

1. 点击服务器行右侧的「编辑」按钮
2. 修改配置
3. 点击「保存」

修改会立即同步到已启用的应用配置文件。

删除服务器

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

删除后，配置会从所有应用的配置文件中移除。

导入现有配置

如果你已经在 CLI 工具中配置了 MCP 服务器，可以导入到 CC Switch：

1. 点击「导入」按钮
2. 选择要导入的应用（Claude/Codex/Gemini/OpenCode）
3. CC Switch 会读取现有配置并导入

配置文件格式

Claude (~/.claude.json)

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

Codex (~/.codex/config.toml)

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

Gemini (~/.gemini/settings.json)

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

常见问题

服务器启动失败

检查：

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

配置不生效

确保：

• 对应应用的开关已开启
• 重启了 CLI 工具