MCP 作用域完全指南

以 chrome-devtools-mcp 为例，深入理解 local / project / user 三种作用域的配置文件位置与优先级规则

---

什么是 MCP 作用域

在 Claude Code 中，每一个 MCP Server 都必须归属于某个作用域（scope）。作用域决定了两件事：

1. 配置被写入哪个文件
2. 这个 Server 在哪些场景下生效

Claude Code 提供三种作用域，通过 --scope（或简写 -s）参数指定：

作用域	-s 参数	写入文件	生效范围
local	默认，可省略	~/.claude.json（项目子键）	仅当前项目，私有
project	-s project	项目根目录/.mcp.json	当前项目，团队共享
user	-s user	~/.claude.json（顶层键）	所有项目，跨项目全局

---

以 chrome-devtools-mcp 为例

chrome-devtools-mcp 让 Claude 能够控制 Chrome 浏览器、读取 Console 输出、执行 JavaScript、截图等，是前端开发的利器。下面展示三种作用域的完整命令：

local scope（默认）

# 不加 -s 参数，默认就是 local
claude mcp add chrome-devtools \
  -- npx -y chrome-devtools-mcp@latest --autoConnect

仅对当前项目生效，配置私有，不会被提交到 Git。适合包含敏感凭据或实验性的配置。

project scope（团队共享）

claude mcp add chrome-devtools -s project \
  -- npx -y chrome-devtools-mcp@latest --autoConnect

写入项目根目录的 .mcp.json，设计为提交到版本控制。团队所有成员打开该项目时都能使用相同的 MCP 工具。首次使用前 Claude Code 会提示确认。

user scope（跨项目全局）

claude mcp add chrome-devtools -s user \
  -- npx -y chrome-devtools-mcp@latest --autoConnect

全局生效，跨所有项目可用，只属于当前用户账户。适合个人常用工具。

关于 -- 分隔符：双横线后面的所有内容都被视为传给 MCP server 的命令和参数，防止 --autoConnect 等参数被 claude mcp add 本身误解析。

---

配置文件写入位置

执行上述命令后，配置实际写入哪里：

~/
├── .claude/
│   └── settings.json          # 全局行为设置（非 MCP）
└── .claude.json               ← local scope 和 user scope 都写这里

~/my-project/
├── .mcp.json                  ← project scope 写这里，建议 git commit
└── .claude/
    └── settings.local.json    # 项目本地设置（非 MCP）

容易混淆的地方：local scope 和 user scope 都写入 ~/.claude.json（Home 目录），区别在于文件内的 JSON 结构不同——local 存在对应项目路径的子键下，user 存在顶层 mcpServers 键下。

~/.claude.json 内部结构示意

{
  "mcpServers": {
    // user scope —— 所有项目生效
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest", "--autoConnect"]
    }
  },
  "projects": {
    "/Users/king/my-project": {
      "mcpServers": {
        // local scope —— 仅 my-project 生效
        "chrome-devtools": {
          "command": "npx",
          "args": ["-y", "chrome-devtools-mcp@latest", "--autoConnect"]
        }
      }
    }
  }
}

.mcp.json（project scope）

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest", "--autoConnect"]
    }
  }
}

---

优先级规则

当同一个 Server 名称在多个作用域都有配置时，Claude Code 按以下顺序决定使用哪个：

local  >  project  >  user
（最高）              （最低）

优先级	作用域	配置位置
1（最高）	local	~/.claude.json → projects["/path"] → mcpServers
2	project	.mcp.json → mcpServers
3（最低）	user	~/.claude.json → mcpServers（顶层）

示例：你在 user scope 配置了 chrome-devtools 的正式版，又在某个项目的 local scope 配置了测试版——在该项目内，local scope 的配置会覆盖 user scope，其他项目仍使用正式版。

.mcp.json 继承：Claude Code 会从当前目录向上搜寻所有父目录的 .mcp.json 并合并加载，子目录可以继承父目录的项目级配置。

---

如何选择作用域

使用场景	推荐作用域	原因
个人实验、含敏感 Token 的配置	local	不进 Git，只影响当前项目
团队统一工具链（如 chrome-devtools）	project	提交 .mcp.json，所有人自动获得
个人日常工具（如笔记、搜索）	user	跨项目复用，无需重复添加

---

验证与管理命令

# 查看所有已配置的 MCP servers
claude mcp list

# 查看某个 server 的详细信息（含 scope）
claude mcp get chrome-devtools

# 删除 project scope 的配置
claude mcp remove chrome-devtools -s project

# 从 Claude Desktop 导入配置
claude mcp add-from-claude-desktop

已知 Bug：目前 claude mcp list 存在已知问题——project scope 的 server 可能不显示在列表中，但实际上是正常工作的。可以用 claude mcp get <name> 单独确认。

---

TL;DR 速查

local   → ~/.claude.json（项目子键）   仅当前项目 · 私有 · 最高优先级
project → .mcp.json（项目根目录）      团队共享 · 可提交 Git · 次优先级
user    → ~/.claude.json（顶层键）      全局 · 跨项目 · 最低优先级

优先级：local > project > user
（同名配置以最高优先级的 scope 为准）

---

参考文档：Claude Code MCP 官方文档