# 3.1 MCP 服务器管理

## 什么是 MCP

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

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

## 打开 MCP 面板

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

## 面板概览

![image-20260108005723522](../../assets/image-20260108005723522.png)

## 添加 MCP 服务器

### 使用预设模板

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

![image-20260108005739731](../../assets/image-20260108005739731.png)

### 常用预设

| 预设 | 包名 | 功能说明 |
|------|------|----------|
| 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（标准输入输出）

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

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

**要求**：
- 需要安装对应的命令（如 `uvx`、`npx`）
- 服务器程序需要在 PATH 中

### http

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

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

### sse（Server-Sent Events）

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

```json
{
  "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 | `~/.config/opencode/opencode.json` 的 `mcp` |
| Hermes | 同步到 Hermes | `~/.hermes/config.yaml` 的 `mcp_servers` |

> ⚠️ **注意**：OpenClaw 和 Claude Desktop 暂不支持 CC Switch MCP 同步。MCP 功能支持 Claude、Codex、Gemini、OpenCode 和 Hermes。

### 开关实现机制

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

1. **更新数据库**：将服务器的 `apps.claude/codex/gemini/opencode/hermes` 状态设为 `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**：需存在 `~/.config/opencode/` 目录
- **Hermes**：需存在 `~/.hermes/` 目录

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

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

## 编辑服务器

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

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

## 删除服务器

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

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

## 导入现有配置

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

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

## 配置文件格式

### Claude (`~/.claude.json`)

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

### Codex (`~/.codex/config.toml`)

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

### Gemini (`~/.gemini/settings.json`)

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

## 常见问题

### 服务器启动失败

检查：
- 命令是否正确安装（如 `uvx`）
- 命令是否在 PATH 中
- 参数是否正确

### 配置不生效

确保：
- 对应应用的开关已开启
- 重启了 CLI 工具