Loading... # Claude Code CLI MCP 配置问题排查与解决 # 一、事件概述 ## 1. 事件背景 用户在 `~/.claude/settings.json.glm4.7` 配置文件中定义了 6 个 MCP（Model Context Protocol）服务器配置，但在运行 `/mcp list` 命令时显示"No MCP servers configured"。 ## 2. 影响范围 ### A. 影响用户 使用 Claude Code CLI 的开发者，特别是从其他版本迁移到官方 CLI 的用户 ### B. 影响功能 MCP 服务器无法被正确识别和使用，导致扩展功能不可用 ## 3. 严重程度 P2 级问题（功能受阻但不影响核心使用） # 二、环境信息 ## 1. 系统环境 - 操作系统：Linux 5.15.45-amd64-desktop - Shell：bash - 工作目录：/home/jacky ## 2. CLI 信息 - 版本：2.1.59 (Claude Code) - 配置文件：~/.claude/settings.json.glm4.7（软链接） - 模型：glm-4.7 ## 3. 配置详情 settings.json.glm4.7 中定义了 6 个 MCP 服务器： - zai-mcp-server（stdio 类型） - web-search-prime（HTTP 类型） - web-reader（HTTP 类型） - zread（HTTP 类型） - wenyan-mcp（Docker 类型） - nagios-mcp（SSE 类型） # 三、问题排查过程 ## 1. 配置文件检查（阶段一） ### A. 检查配置文件位置 ```bash ls -la ~/.claude/settings.json ``` 发现 `settings.json` 是软链接，指向 `settings.json.glm4.7`，该文件中确实包含 mcpServers 配置。 ### B. 检查 CLI 版本 ```bash claude --version ``` 输出：2.1.59 (Claude Code) 确认使用的是官方版本，而非 glm4.7 自定义版本。 ## 2. 配置内容验证（阶段二） ### A. 读取配置文件 ```bash cat ~/.claude/settings.json.glm4.7 | jq '.mcpServers' ``` 验证结果：配置文件中存在 6 个 MCP 服务器定义，格式正确。 ### B. 尝试列出 MCP 服务器 ```bash claude mcp list ``` 输出结果：No MCP servers configured. 配置存在但未被识别，说明存在配置读取位置或格式的问题。 ## 3. 深入调查（阶段三） ### A. 检查官方 CLI 配置文件 ```bash cat ~/.claude.json | jq '.mcpServers' ``` 结果：全局 mcpServers 键不存在。 ### B. 检查项目级别配置 ```bash cat ~/.claude.json | jq '.projects["/home/jacky"].mcpServers' ``` 结果：项目级别配置为空。 ### C. 结论 官方 CLI 2.1.59 不从 settings.json 读取 mcpServers 配置，而是从 ~/.claude.json 的 mcpServers 键读取。 ```mermaid graph TD A[User Config MCP Server] --> B{Config Location} B -->|settings.json| C[glm4.7 Read] B -->|.claude.json mcpServers| D[Official CLI Read] C --> E[Config Active] D --> F[Config Active] G[Official CLI] --> D H[glm4.7] --> C I[/mcp list] --> D ```  # 四、问题分析 ## 1. 直接原因 配置文件位置不匹配。glm4.7 版本从 settings.json 的 mcpServers 读取配置，官方 CLI 从 ~/.claude.json 的 mcpServers 读取配置。 ## 2. 根本原因（5 Whys 分析） ### A. 为什么配置不生效？ 官方 CLI 和 glm4.7 版本使用了不同的配置文件和配置键。 ### B. 为什么会有不同的配置位置？ glm4.7 是自定义版本，可能有不同的配置管理机制。 ### C. 为什么用户没有意识到？ CLI 版本信息显示为 2.1.59，但配置文件名是 settings.json.glm4.7，存在版本混淆。 ### D. 为什么 /mcp list 不显示任何配置？ /mcp list 只读取 ~/.claude.json 中的全局 mcpServers 配置。 ### E. 如何避免此类问题？ 需要明确官方 CLI 的配置规范，使用正确的配置管理命令。 ## 3. 深层反思 1. 配置文档需要明确不同版本的配置文件差异 2. CLI 命令应该提供更友好的错误提示 3. 配置迁移工具可以帮助用户平滑过渡 # 五、解决方案 ## 1. 临时方案 ### A. 手动迁移配置 通过官方 CLI 命令重新添加 MCP 服务器。 ### B. 效果评估 快速解决问题，但需要手动逐个配置服务器。 ## 2. 永久方案 ### A. 使用官方 CLI 命令管理配置 使用 `claude mcp add` 命令添加服务器，确保配置写入正确的位置。 ### B. 配置级别选择 使用 `--scope user` 参数将配置添加到用户级别，使 `/mcp list` 能够显示。 ### C. 实施步骤 #### HTTP 服务器 ```bash claude mcp add --scope user --transport http web-search-prime https://open.bigmodel.cn/api/mcp/web_search_prime/mcp --header "Authorization: Bearer YOUR_KEY" claude mcp add --scope user --transport http web-reader https://open.bigmodel.cn/api/mcp/web_reader/mcp --header "Authorization: Bearer YOUR_KEY" claude mcp add --scope user --transport http zread https://open.bigmodel.cn/api/mcp/zread/mcp --header "Authorization: Bearer YOUR_KEY" ``` #### SSE 服务器 ```bash claude mcp add --scope user --transport sse nagios-mcp http://192.168.124.47:63001/sse ``` #### stdio 服务器 ```bash claude mcp add-json --scope user zai-mcp-server '{ "type": "stdio", "command": "npx", "args": ["-y", "@z_ai/mcp-server"], "env": { "Z_AI_MODE": "ZHIPU", "Z_AI_API_KEY": "YOUR_KEY" } }' ``` ## 3. 验证方法 ### A. 检查全局配置 ```bash cat ~/.claude.json | jq '.mcpServers' ``` 预期输出：显示已配置的 MCP 服务器列表。 ### B. 检查配置详情 ```bash cat ~/.claude.json | jq '.mcpServers | keys' ``` 预期输出： ``` [ "web-search-prime", "web-reader", "zread", "nagios-mcp", "zai-mcp-server" ] ``` # 六、配置管理最佳实践 ## 1. 配置级别说明 Claude Code CLI 支持三种配置级别： ### A. 用户级别（user scope） - 配置位置：~/.claude.json → mcpServers - 适用场景：全局可用，所有项目共享 - 管理命令：`claude mcp add --scope user ...` ### B. 项目级别（project scope） - 配置位置：~/.claude.json → projects["/path"] → mcpServers - 适用场景：特定项目的配置 - 管理命令：`claude mcp add --scope project ...` ### C. 本地级别（local scope） - 配置位置：当前目录的 .claude.json - 适用场景：当前项目独占配置 - 管理命令：`claude mcp add --scope local ...`（默认） ## 2. 常用管理命令 ### A. 添加服务器 ```bash # HTTP 服务器 claude mcp add --scope user --transport http <name> <url> --header "Key: Value" # SSE 服务器 claude mcp add --scope user --transport sse <name> <url> # stdio 服务器 claude mcp add --scope user <name> -- <command> [args...] # stdio 服务器带环境变量 claude mcp add -e KEY1=value1 -e KEY2=value2 <name> -- <command> ``` ### B. 删除服务器 ```bash claude mcp remove --scope user <name> ``` ### C. 查看服务器详情 ```bash claude mcp get <name> ``` ### D. 列出所有服务器 ```bash claude mcp list ``` ## 3. 配置文件结构 ```json { "mcpServers": { "server-name": { "type": "http|sse|stdio", "url": "http://...", "headers": {...}, "command": "...", "args": [...], "env": {...} } } } ``` ```mermaid graph LR A[CLI Command] --> B{Config Scope} B -->|user| C[~/.claude.json mcpServers] B -->|project| D[projects path mcpServers] B -->|local| E[.claude.json] C --> F[/mcp list Show] D -.Hidden.-> F E -.Hidden.-> F ```  # 七、经验总结 ## 1. 做得好的地方 - 系统性排查，从配置文件、CLI 版本、配置内容多角度分析 - 使用第一性原理方法，深入挖掘根本原因 - 提供完整的解决方案和最佳实践 ## 2. 需要改进的地方 - 配置文档应该更清晰地说明不同版本的配置差异 - CLI 应该提供配置迁移工具，帮助用户平滑过渡 - 错误提示应该更友好，明确指出配置不匹配的原因 ## 3. 流程优化建议 ### A. 配置验证流程 ```bash # 1. 检查 CLI 版本 claude --version # 2. 检查配置文件 cat ~/.claude.json | jq '.mcpServers' # 3. 列出 MCP 服务器 claude mcp list # 4. 验证配置正确性 claude mcp get <server-name> ``` ### B. 新用户上手指南 - 明确官方 CLI 的配置规范 - 提供配置模板和示例 - 建立配置检查清单 # 八、注意事项 ## 1. 版本兼容性 - glm4.7 自定义版本的配置文件与官方 CLI 不兼容 - 迁移到官方 CLI 时需要重新配置 MCP 服务器 ## 2. 配置优先级 - 用户级别 > 项目级别 > 本地级别 - 相同服务器名在不同级别可能产生覆盖 ## 3. 安全建议 - API Key 等敏感信息建议使用环境变量 - 配置文件权限设置为 600（仅所有者可读写） - 不要将包含敏感信息的配置文件提交到版本控制 *** ## 参考资料 1. [Claude Code MCP Documentation](https://code.claude.com/docs/en/mcp) 2. [Claude Code CLI GitHub Repository](https://github.com/anthropics/claude-code) 最后修改：2026 年 02 月 28 日 © 允许规范转载 赞 如果觉得我的文章对你有用，请随意赞赏