mcp-installer

MCP 安装程序

概览

通过 CLI 优先的工作流，在多个客户端和操作系统上安装 MCP 服务配置，并提供安全的手动备用方案。

工作流

1) 收集输入信息

• 确定目标客户端 ID 和操作系统；支持列表及已知路径请参阅 references/clients.md。
• 收集 MCP 服务定义（名称 -> 配置对象），并决定是否覆盖现有条目。
• 如果提供的任何 MCP 配置包含密钥（例如 key、token、apiKey、accessToken、secret、password 或 Authorization 等字段，或 *_KEY、*_TOKEN 等环境变量），请暂停安装，并询问用户是否可以先获取/提供这些值。只有在用户确认已拥有所需凭据（或要求先安装占位值，之后再自行填写）后，才继续操作。

2) 优先使用 @smithery/cli（支持时）

• 运行 npx @smithery/cli --help 和 npx @smithery/cli install --help，确认准确语法。
• 对客户端 ID 使用 CLI 安装流程；如果 CLI 拒绝该客户端或运行失败，则回退到手动编辑。

3) 手动安装（JSON 配置备用方案）

• 定位配置文件路径（请参阅 references/clients.md）。如果路径未知，请在标准配置目录中搜索 mcp.json、mcp_config.json、claude_desktop_config.json 或 cline_mcp_settings.json 等文件。
• 读取现有 JSON，并确保存在顶层 mcpServers 对象。
• 合并服务：添加新名称；当 override 为 true 时替换现有条目；保留所有其他键。
• 使用 2 个空格缩进写入 JSON。

示例结构：

{
  "mcpServers": {
    "example-server": {
      "command": "npx",
      "args": ["-y", "example-mcp@latest"],
      "env": {}
    }
  }
}

4) 验证和排查问题

• 重启客户端并确认 MCP 服务已显示。
• 如果在 macOS 上写入失败，请提示用户授予“完全磁盘访问权限”，并确保写入前已关闭客户端应用。
• 对于仅支持 CLI 的客户端（例如 claude-code），使用客户端 CLI 帮助来查找其 MCP 安装/配置命令。
• 如果 Trae/Trae-CN 因权限或其他错误而安装失败，请生成深层链接并将其作为备用方案返回。

5) Trae 深层链接备用方案

如果 trae 或 trae-cn 无法写入磁盘，请生成一个架构链接，供用户在 Trae 中打开：

• trae：trae://trae.ai-ide/mcp-import?type=${TYPE}&name=${NAME}&config=${BASE64_ENCODED_CONFIG}
• trae-cn：trae-cn://trae.ai-ide/mcp-import?type=${TYPE}&name=${NAME}&config=${BASE64_ENCODED_CONFIG}

规则：

• TYPE 是 MCP 传输类型（例如 streamable-http）。
• NAME 是在 Trae 中显示的服务名称。
• config 是该服务 JSON 配置对象的 Base64 编码（无空白字符，UTF-8 字节）。

参考资料

• 客户端 ID、别名和已知配置路径请参阅 references/clients.md。