# Install MCP

> Use when 用户需要盘点、规划或批量安装 MCP 配置，确认各 agent 的配置目标、JSON 或 TOML 形态、合并策略、dry-run、备份或第三方 server entry 时。

- Skill: `ruan-cat/install-mcp` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ruan-cat/install-mcp`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ruan-cat/install-mcp/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ruan-cat (https://skillmd.com/u/ruan-cat)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ruan-cat/install-mcp

---


# install-mcp

## 职责边界

本技能是 MCP 配置的清单与调度入口，不新增安装脚本。执行模型应根据本清单完成预览、备份和精确写入；本技能不替代任何专用安装器。

- Memorix full mode 的实际安装与校验交给 `init-simple-memorix`。
- 通用第三方 MCP 仅在确认 server entry schema、`command`、`args`、`env` 和信任审批影响后处理。
- 所有写入必须以保留既有配置为前提，不能覆盖其他 `mcpServers`。

## 已知配置目标

| 平台         | 配置路径                                             | 格式 |
| :----------- | :--------------------------------------------------- | :--- |
| Codex        | `~/.codex/config.toml`                               | TOML |
| Codex        | `~/.codex/config-2026-6-13-bg.toml`                  | TOML |
| Claude Code  | `~/.claude.json`                                     | JSON |
| Cursor       | `~/.cursor/mcp.json`                                 | JSON |
| WorkBuddy    | `~/.workbuddy/mcp.json`                              | JSON |
| WorkBuddy    | `~/.workbuddy/.mcp.json`                             | JSON |
| ZCode        | `~/.zcode/cli/config.json`                           | JSON |
| Qoder        | `~/AppData/Roaming/Qoder/SharedClientCache/mcp.json` | JSON |
| Qoder        | `~/.qoder/mcp.json`                                  | JSON |
| MiniMax Code | `~/.minimax/mcp/mcp.json`                            | JSON |
| Kiro         | `~/.kiro/settings/mcp.json`                          | JSON |

## 配置合并规则

- JSON 配置通常以 `mcpServers` 对象保存 server entries；只新增或更新目标 entry，保留未知顶层字段和其他 entries。
- TOML 配置使用其既有的 MCP server table 形态；只修改目标 table，保留注释、未知字段和其他 server tables。
- 先解析当前文件并生成 dry-run 预览，再经授权写入；真实写入前为原文件创建可识别的备份。
- 配置不存在时，先确认该平台接受的最小文件结构后才创建；配置解析失败或结构不明时停止写入并报告。
- 不用模板整体覆盖现有配置，也不假设不同平台的 JSON entry 可以直接互换。

## WorkBuddy 特别处理

WorkBuddy 可能向子进程注入 Node 参数。对需要隔离 Node 参数的 MCP entry，可建议设置 `env.NODE_OPTIONS = ""`。这是兼容性建议，不代表所有脚本或所有配置都会自动补齐该字段。

变更 WorkBuddy 的 MCP entry 可能触发新的信任审批；写入后应提示重启应用并重新确认 server 连接状态。

## MiniMax Code 特别处理

`~/.minimax/mcp/mcp.json` 是 MiniMax Code 本地 agent 工具的用户级 MCP 配置，顶层结构为 `mcpServers`，但 entry 字段比通用 JSON 配置更丰富：

- stdio 形态 entry 使用 `command`、`args`、`env`；远程形态 entry 使用 `url` + `type: "streamable-http"`，可带 `headers` 鉴权字段。
- entry 常携带 `enabled`、`configured`、`builtin`、`description`、`timeout` 等平台元数据字段，合并时必须原样保留，不得删除或改写。
- `builtin: true` 的 entry 是 MiniMax Code 自管的内置服务；批量安装只新增或更新非内置 entry，不修改、不删除内置 entry。
- 新增 entry 时优先对照该文件内既有非内置 entry 的字段形态，不臆测平台必需字段集合。

该文件及同目录的 `tokens.json` 可能包含 Bearer token 或 API key：dry-run 预览、备份与报告不得原样输出这些敏感字段，也不得将其写入提交或日志。

## Qoder 特别处理

`~/.qoder/mcp.json` 是单纯的 Qoder agent 工具的用户级 MCP 配置，顶层结构为 `mcpServers`，entry 为极简形态（通常只有 `command`、`args`，可选 `type`）。合并时保持极简形态，不要注入其他平台的元数据字段。注意目标文件是 `mcp.json`，不是同目录的 `mcp-router.json`。

Qoder 系目录归属极易混淆，写入前必须逐个审计目录归属：

- `~/.qoder-cli`、`~/.qoder-cn`、`~/.qoderwork`、`~/.qoderworkcn` 等是不同产品的目录，都不是单纯的 Qoder。
- 其中 `~/.qoder-cn/mcp.json`、`~/.qoderworkcn/mcp.json` 同样真实存在，但它们不是本技能的可写目标；不得因名称相似而跨写。
- 清单中的 `~/AppData/Roaming/Qoder/SharedClientCache/mcp.json` 与 `~/.qoder/mcp.json` 是两个相互独立的配置位置，写入前必须明确本次针对哪一个。
- `~/.qoder` 目录下还有 `extensions/`、`plugins/`、`skills/`、`memories/` 等 Qoder 运行态目录；批量 MCP 安装只写 `mcp.json`，不触碰其他目录。

## Memorix 与第三方 MCP 调度

| 场景              | 调度规则                                                                          |
| :---------------- | :-------------------------------------------------------------------------------- |
| Memorix full mode | 交给 `init-simple-memorix`，不要在本技能中重复其安装细节。                        |
| 已知第三方 server | 先核对该 server 的官方 entry schema、命令、参数、环境变量和信任影响，再精确合并。 |
| 未知第三方 server | 不写入；先取得可靠配置来源与用户授权。                                            |

## Future candidates

Antigravity、Trae、Gemini CLI 等仅为候选平台。只有在找到可靠、可验证的 MCP 配置路径及其格式后，才可加入“可写目标”；不得因常见命名或历史印象写死路径。Qoder 系相似目录（如 `~/.qoder-cn`、`~/.qoderworkcn`）中已存在的 `mcp.json` 属于不同产品，未经归属确认与用户明确授权，不得纳入可写目标。

## 执行与验收

1. 从已知配置清单中选择实际存在且获得授权的目标，确认 JSON 或 TOML 结构。
2. 构造仅影响目标 server entry 的 dry-run 变更，明确说明会保留的字段、备份位置和可能的信任审批影响。
3. 写入后重新解析配置，确认其他 `mcpServers` 未变化，并按平台要求重启或刷新后检查 server 状态。