Three scopes:

1. Local (default, --scope local) - Stored in ~/.claude.json under specific project path, only works in that directory
2. Project (--scope project) - Stored in .mcp.json at project root, can be shared via git with team
3. User (--scope user) - Stored in ~/.claude.json globally, works across ALL projects

---

一、三种配置作用域对比

Claude Code 的 MCP 配置有三个层级，搞清楚了就不会配错：

作用域	命令参数	存储位置	生效范围
Local（默认）	--scope local 或不写	~/.claude.json（按项目路径存）	❌ 仅当前目录
Project（项目级）	--scope project	项目根目录 .mcp.json	❌ 仅该项目
User（用户级）✅	--scope user	~/.claude.json（全局）	✅ 所有项目

---

二、一行命令搞定全局配置

Windows（PowerShell）

claude mcp add-json --scope user tavily-search '{"command":"cmd","args":["/c","npx","-y","tavily-mcp"],"env":{"TAVILY_API_KEY":"你的API_KEY"}}'

Mac / Linux（终端）

claude mcp add-json --scope user tavily-search '{"command":"npx","args":["-y","tavily-mcp"],"env":{"TAVILY_API_KEY":"你的API_KEY"}}'

关键点：--scope user 是精髓，它告诉 Claude Code “把这个 MCP 存到全局配置里，别只存当前项目”。

---

三、验证是否配置成功

第1步：查看 MCP 列表

claude mcp list

输出中应该能看到类似：

tavily-search (user)   ✅ connected
  → tools: tavily_search, tavily_extract

看到 (user) 后缀就说明是全局的了。

第2步：查看配置文件

打开 ~/.claude.json（Windows: C:\Users\你的用户名\.claude.json），应该能看到：

{
  "mcpServers": {
    "tavily-search": {
      "command": "npx",
      "args": ["-y", "tavily-mcp"],
      "env": {
        "TAVILY_API_KEY": "tvly-xxxxxxxxxxxx"
      }
    }
  }
}

注意区别：

• ✅ 全局配置：mcpServers 位于 JSON 的顶层 → 所有项目共享
• ❌ 项目配置：mcpServers 嵌套在 projects.某个路径 下面 → 仅该目录生效

第3步：换个项目试试

cd ~/any-other-project
claude
# 在 Claude Code 中输入：
> 搜索一下今天的热点新闻

如果在任意目录都能调用 tavily_search，恭喜，全局配置生效！

---

四、全局配置的本质：一图看懂

~/.claude.json （用户主目录下的全局配置文件）
│
├── mcpServers ← 顶层，user scope 配置存在这里
│   └── tavily-search: { ... }    ← 🔵 所有项目都能用
│
├── projects ← local scope 按项目路径存储
│   ├── /home/user/project-a
│   │   └── mcpServers: { ... }   ← 🟢 仅 project-a 能用
│   └── /home/user/project-b
│       └── mcpServers: { ... }   ← 🟢 仅 project-b 能用
│
└── ...其他配置...

项目根目录/.mcp.json ← project scope
    └── mcpServers: { ... }       ← 🟡 团队共享，git 提交

优先级（同名 MCP 冲突时）：project > local > user

比如 user 和 project 都配了 tavily-search，实际用的是 project 里的配置。

---

五、常见补充操作

1. 更新全局 MCP（如换了 API Key）

直接重新执行配置命令即可，会覆盖之前的：

claude mcp add-json --scope user tavily-search '{"command":"npx","args":["-y","tavily-mcp"],"env":{"TAVILY_API_KEY":"新的API_KEY"}}'

或者直接编辑 ~/.claude.json：

{
  "mcpServers": {
    "tavily-search": {
      "command": "npx",
      "args": ["-y", "tavily-mcp"],
      "env": {
        "TAVILY_API_KEY": "新的API_KEY"
      }
    }
  }
}

2. 删除全局 MCP

claude mcp remove tavily-search --scope user

3. 添加第二个搜索 MCP（作为备选）

# Tavily 搜不到的就用 Brave
claude mcp add-json --scope user brave-search '{"command":"npx","args":["-y","@anthropic-ai/mcp-server-brave-search"],"env":{"BRAVE_API_KEY":"你的BRAVE_API_KEY"}}'

两个可以共存，Claude Code 会智能选择调用哪个。

---

六、总结

目标：让 Tavily MCP 在所有 Claude Code 项目中生效

方法：在配置命令中加 --scope user

命令：claude mcp add-json --scope user tavily-search '{"command":"npx",...}'

验证：claude mcp list → 看到 (user) 标识 + 换任意目录测试

一句话记住：--scope user = 全局通用，--scope project = 团队共享，不写 scope = 仅当前目录。你要的就是 --scope user。