claude-code-mcp-guide.md

Claude Code MCP 配置指南

MCP 服务器的三层来源

┌──────────────────────────────────────────────────┐
│ 第 1 层：Built-in 插件 MCP（始终可用）              │
│ plugin:context7, plugin:playwright, plugin:github  │
│ → 不受任何配置文件控制，始终加载                      │
└──────────────────────────────────────────────────┘
                         +
┌──────────────────────────────────────────────────┐
│ 第 2 层：用户配置的 MCP（settings.json 或 .claude.json）│
│ codegraph, memory, sequential-thinking, lark-mcp  │
│ → 受以下覆盖链控制                                  │
└──────────────────────────────────────────────────┘

配置文件

文件	路径	维护者	用途
settings.json	~/.claude/settings.json	用户手动编辑	全局偏好：模型、权限、MCP 服务器
.claude.json	~/.claude.json	Claude Code 自动生成	运行时状态：项目统计、项目级 MCP

覆盖规则（核心）

.claude.json 项目级的 mcpServers 完全覆盖 settings.json 的 mcpServers，不是合并。

判定流程

Claude Code 启动
    │
    ├─ 检查 .claude.json → projects[当前项目路径]
    │
    ├─ 该项目的 mcpServers 是否有内容？
    │   ├─ YES → 使用项目级，忽略 settings.json
    │   ├─ {}  → 空对象，但 key 存在，也忽略 settings.json ⚠️
    │   └─ key 不存在 → 回退 settings.json
    │
    └─ + 第 1 层 Built-in 插件 MCP（始终附加）

关键陷阱

Claude Code 为新项目自动创建 "mcpServers": {}。按逻辑 {} 应该表示"没有项目级配置，用全局的"，但实际行为是：

mcpServers: {}     ← key 存在 → "走项目级" → 空配置，全局 MCP 全部丢失
mcpServers 未定义  ← key 不存在 → "走全局" → 用 settings.json

实际案例

正常项目 (04_claude_use)

settings.json mcpServers: { codegraph, memory, sequential-thinking }
.claude.json projects[项目]: { codegraph, lark-mcp, memory, sequential-thinking }

结果: 使用项目级（4 个）+ Built-in 插件 = 8 个

新项目（修复前）

.claude.json projects[项目]: mcpServers: {}

结果: 只有 4 个 Built-in 插件，全局 MCP 全部丢失

修复方式

方式 1：手动把 settings.json 的 MCP 配置复制到 .claude.json 对应项目条目下 方式 2：删除项目的 mcpServers key（但 Claude 可能重新创建 {}） 方式 3（推荐）：用 /mcp 面板添加/启用服务器

同步时机

时机	行为
首次在某目录启动 Claude	创建项目条目，mcpServers: {}
使用 /mcp 面板操作	更新 mcpServers、enabledMcpjsonServers
每次会话结束	更新统计字段（lastCost、lastDuration）

不会自动将 settings.json 的全局 MCP 同步到 .claude.json。

.claude.json 顶层 mcpServers

"mcpServers": {}

这是 .claude.json 的顶层字段，始终为 {}，是 /mcp 面板（全局视图）的持久化占位，不参与项目级解析，不需要手动修改。