Claude-Code-Workflow/ccw/docs/mcp-manager-guide.md

MCP Manager - 使用指南

概述

全新的 MCP 管理器提供了统一的界面来管理 MCP 服务器，支持多种安装方式和配置管理。

主要特性

1. 统一的 MCP 编辑弹窗

• 三种模式：

  • 创建模式（Create）：创建新的 MCP 服务器
  • 编辑模式（Edit）：编辑现有 MCP 服务器
  • 查看模式（View）：只读查看 MCP 服务器详情

• 两种服务器类型：

  • STDIO (Command-based)：通过命令行启动的 MCP 服务器
  • HTTP (URL-based)：通过 HTTP/HTTPS 访问的 MCP 服务器

2. 多种安装目标

支持安装到以下位置：

目标	配置文件	说明
Claude	.mcp.json	项目级配置，推荐用于 Claude CLI
Codex	~/.codex/config.toml	Codex 全局配置
Project	.mcp.json	项目级配置（与 Claude 相同）
Global	~/.claude.json	全局配置，所有项目可用

3. MCP 模板系统

• 保存模板：从现有 MCP 服务器创建可复用模板
• 浏览模板：按分类查看所有已保存的模板
• 一键安装：从模板快速安装 MCP 服务器到任意目标

4. 统一的服务器管理

• 查看所有服务器：

  • Project（项目级）
  • Global（全局级）
  • Codex（Codex 全局）
  • Enterprise（企业级，只读）

• 操作：

  • 启用/禁用
  • 查看详情
  • 编辑配置
  • 删除服务器
  • 保存为模板

使用方法

创建新的 MCP 服务器

1. 点击 "Create New" 按钮

2. 填写服务器信息：

   • 名称：唯一标识符（必填）
   • 描述：简要说明（可选）
   • 分类：从预定义分类中选择

3. 选择服务器类型：

   • STDIO：填写 command、args、env、cwd
   • HTTP：填写 url、HTTP 头

4. （可选）勾选 "Save as Template" 保存为模板

5. 选择安装目标（Claude/Codex/Project/Global）

6. 点击 "Install" 完成安装

STDIO 服务器示例

{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory"],
  "env": {
    "DEBUG": "true"
  }
}

HTTP 服务器示例

{
  "url": "https://api.example.com/mcp",
  "http_headers": {
    "Authorization": "Bearer YOUR_TOKEN",
    "X-API-Key": "YOUR_KEY"
  }
}

从模板安装

1. 点击 "Templates" 按钮
2. 浏览分类中的模板
3. 点击模板卡片上的 "Install" 按钮
4. 在弹窗中修改配置（如需要）
5. 选择安装目标
6. 点击 "Install"

编辑现有服务器

1. 在服务器列表中找到目标服务器
2. 点击 编辑图标（✏️）
3. 修改配置
4. 点击 "Update" 保存更改

管理服务器

• 启用/禁用：点击开关图标（🔄）
• 查看详情：点击眼睛图标（👁️）
• 保存为模板：点击书签图标（🔖）
• 删除：点击垃圾桶图标（🗑️）

CLI 模式切换

支持两种 CLI 模式：

• Claude 模式：管理 ~/.claude.json 和 .mcp.json 中的服务器
• Codex 模式：管理 ~/.codex/config.toml 中的服务器

在界面顶部切换 CLI 模式以查看和管理相应的服务器。

统计信息

仪表板顶部显示以下统计：

• Total Servers：总服务器数量
• Enabled：已启用的服务器数量
• Claude：Claude 相关服务器数量（Project + Global）
• Codex：Codex 服务器数量

服务器分类

预定义分类：

• Development Tools
• Data & APIs
• Files & Storage
• AI & ML
• DevOps
• Custom

API 支持

后端 API 已完整实现，支持：

Claude MCP API

• POST /api/mcp-copy-server - 安装到项目/全局
• POST /api/mcp-remove-server - 从项目删除
• POST /api/mcp-add-global-server - 添加全局服务器
• POST /api/mcp-remove-global-server - 删除全局服务器
• POST /api/mcp-toggle - 启用/禁用服务器

Codex MCP API

• POST /api/codex-mcp-add - 添加 Codex 服务器
• POST /api/codex-mcp-remove - 删除 Codex 服务器
• POST /api/codex-mcp-toggle - 启用/禁用 Codex 服务器
• GET /api/codex-mcp-config - 获取 Codex 配置

模板 API

• GET /api/mcp-templates - 获取所有模板
• POST /api/mcp-templates - 保存模板
• DELETE /api/mcp-templates/:name - 删除模板
• GET /api/mcp-templates/search?q=keyword - 搜索模板
• GET /api/mcp-templates/categories - 获取所有分类

配置文件格式

.mcp.json (项目级)

{
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["server.js"],
      "env": {}
    }
  }
}

.claude.json (全局级)

{
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["server.js"]
    }
  }
}

config.toml (Codex)

[mcp_servers.server-name]
command = "node"
args = ["server.js"]
enabled = true

故障排除

常见问题

1. 服务器无法启用

   • 检查命令是否正确
   • 确认依赖是否已安装
   • 查看环境变量是否正确

2. 无法保存到 Codex

   • 确认 ~/.codex 目录存在
   • 检查文件权限

3. 模板无法加载

   • 刷新页面重试
   • 检查浏览器控制台错误信息

调试技巧

• 打开浏览器开发者工具查看网络请求
• 检查控制台日志
• 查看配置文件是否正确生成

兼容性

• 支持的配置格式：

  • .mcp.json (JSON)
  • .claude.json (JSON)
  • config.toml (TOML for Codex)

• 浏览器支持：

  • Chrome/Edge (推荐)
  • Firefox
  • Safari

最佳实践

1. 使用 .mcp.json 优先：

   • 便于版本控制
   • 项目独立配置
   • Claude 和 Codex 都能识别

2. 分类管理模板：

   • 为模板选择合适的分类
   • 添加清晰的描述
   • 避免重复的模板名称

3. 环境变量安全：

   • 敏感信息使用环境变量
   • 不要在配置文件中硬编码 token
   • 使用 .env 文件管理密钥

4. 服务器命名规范：

   • 使用小写字母和连字符
   • 避免特殊字符
   • 名称具有描述性

更新日志

v2.0 (当前版本)

• ✅ 全新的统一编辑弹窗
• ✅ 支持多种安装目标（Claude/Codex/Project/Global）
• ✅ 完整的模板系统
• ✅ STDIO 和 HTTP 服务器类型支持
• ✅ 统一的服务器列表视图
• ✅ 实时统计信息
• ✅ 国际化支持（英文/中文）
• ✅ 响应式设计

从旧版本迁移

旧版本的 MCP 配置会自动识别，无需手动迁移。新版本完全兼容旧配置文件。

支持

如有问题或建议，请联系开发团队或提交 issue。