AI编程—claude code中plugin三种范围模式的配置方法

Three scopes:

Local (default, --scope local) - Stored in ~/.claude.json under specific project path, only works in that directory
Project (--scope project) - Stored in .mcp.json at project root, can be shared via git with team
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）

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（终端）

bash 复制代码

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 列表

bash 复制代码

claude mcp list

输出中应该能看到类似：

复制代码

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

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

第2步：查看配置文件

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

json 复制代码

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

注意区别：

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

第3步：换个项目试试

bash 复制代码

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）

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

bash 复制代码

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

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

json 复制代码

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

2. 删除全局 MCP

bash 复制代码

claude mcp remove tavily-search --scope user

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

bash 复制代码

# 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。