Claude Code教程（五）| MCP指南

[一、什么是 MCP](#一、什么是 MCP)
[二、Claude Code 配置体系的历史演进](#二、Claude Code 配置体系的历史演进)
三、配置层级与官方优先级（真实且固定）
四、全局配置（用户级）完整文件体系
- [4.1 全局配置文件分类（必选+可选）](#4.1 全局配置文件分类（必选+可选）)
- [4.2 全局文件真实路径（全操作系统）](#4.2 全局文件真实路径（全操作系统）)
- - [4.2.1 Windows 系统](#4.2.1 Windows 系统)
  - [4.2.2 macOS / Linux 系统](#4.2.2 macOS / Linux 系统)
五、项目级配置（团队协作标准）
- [5.1 项目共享配置（提交 Git）](#5.1 项目共享配置（提交 Git）)
- [5.2 项目本地配置（不上 Git）](#5.2 项目本地配置（不上 Git）)
六、企业托管配置（普通用户可略过）
- [6.1 核心作用](#6.1 核心作用)
- [6.2 系统路径（全操作系统）](#6.2 系统路径（全操作系统）)
- - [6.2.1 Windows 系统](#6.2.1 Windows 系统)
  - [6.2.2 macOS 系统](#6.2.2 macOS 系统)
  - [6.2.3 Linux 系统](#6.2.3 Linux 系统)
- [6.3 核心特性](#6.3 核心特性)
七、各配置文件完整内容示例（可直接复制）
- [7.1 全局 `.claude.json`（默认常用结构）](#7.1 全局 .claude.json（默认常用结构）)
- [7.2 全局 `settings.json`（规则拆分版）](#7.2 全局 settings.json（规则拆分版）)
- [7.3 全局 `mcp.json`（纯 MCP 定义版）](#7.3 全局 mcp.json（纯 MCP 定义版）)
- [7.4 项目 `.mcp.json`（团队共享）](#7.4 项目 .mcp.json（团队共享）)
- [7.5 项目 `settings.json`（团队共享）](#7.5 项目 settings.json（团队共享）)
- [7.6 项目 `settings.local.json`（个人本地）](#7.6 项目 settings.local.json（个人本地）)
八、官方优先级规则（避坑关键）
[九、MCP 标准字段完整说明（官方固定）](#九、MCP 标准字段完整说明（官方固定）)
- [9.1 stdio 类型（本地进程，最常用）](#9.1 stdio 类型（本地进程，最常用）)
- [9.2 http / sse 类型（远程 MCP 服务）](#9.2 http / sse 类型（远程 MCP 服务）)
十、最佳实践（可直接落地）
- [10.1 个人新手最简方案（推荐 90% 个人用户）](#10.1 个人新手最简方案（推荐 90% 个人用户）)
- [10.2 进阶整洁方案（个人进阶用户）](#10.2 进阶整洁方案（个人进阶用户）)
- [10.3 团队标准方案（团队协作首选）](#10.3 团队标准方案（团队协作首选）)
- [10.4 安全规范（必看）](#10.4 安全规范（必看）)
十一、常见问题与避坑指南（新手必看）
十二、总结

一、什么是 MCP

MCP（Model Context Protocol）是 Anthropic 推出的标准化工具调用协议 ，

核心作用是让 Claude Code 安全、结构化地访问外部资源（本地文件系统、数据库、Git 仓库、第三方 API 等），是 Claude Code 突破原生能力边界的核心入口。

二、Claude Code 配置体系的历史演进

Claude Code 配置体系经历了「单文件大一统」到「模块化拆分」的清晰演进，核心目的是提升可维护性与团队协作效率，具体分为三个阶段：

早期架构（单文件大一统） ：所有配置（登录态、UI 偏好、MCP 服务、权限、环境变量等）集中在 ~/.claude.json，结构臃肿、维护不便。
现代架构（职责分离）：官方拆分出两类模块化文件，与原有兜底文件互补：
- 行为规则层：权限、开关、环境变量管理 → settings.json
- MCP 定义层：仅 MCP 服务器声明与配置 → mcp.json
- 全局兜底层：会话缓存、登录信息、旧配置兼容 → .claude.json
项目级独立配置：新增项目级配置，仅对当前项目生效，可灵活覆盖全局配置，实现工程隔离与团队统一规范。

关键点：.claude.json 未被废弃，settings.json/mcp.json 是可选增强，非强制替换，确保向后兼容。

三、配置层级与官方优先级（真实且固定）

Claude Code 配置遵循「高优先级覆盖低优先级」策略，同名配置高优先级直接替换低优先级（不深度合并），官方明确优先级从高到低排序如下：

企业托管配置（Managed）：系统级配置，企业 IT 统一下发，对整台机器所有用户生效，普通用户无法修改，用于安全合规管控。
命令行临时参数：启动时传入，仅当前会话有效，适合临时调试。
项目本地配置 ：项目/.claude/settings.local.json，仅当前用户、当前项目生效，存储敏感信息，不上 Git。
项目共享配置 ：项目/.mcp.json + 项目/.claude/settings.json，团队共用，推荐提交 Git，统一配置规范。
用户全局配置：对当前用户所有项目生效，内部优先级：
- ~/.claude/settings.json（可选，行为规则拆分）
- ~/.claude/mcp.json（可选，纯 MCP 定义）
- ~/.claude.json（默认兜底，必选，自动生成）

四、全局配置（用户级）完整文件体系

全局配置对当前用户所有项目生效，按「必选/可选」分类，清晰说明各文件的作用、路径与核心信息。

4.1 全局配置文件分类（必选+可选）

文件路径	必选/可选	核心作用	是否自动生成
`~/.claude.json`	必选	全局兜底，存储登录会话、UI 偏好、MCP 服务、权限、环境变量	是（安装后首次启动自动生成）
`~/.claude/settings.json`	可选	行为规则拆分，仅存储权限、环境变量、MCP 开关	否（手动创建或 CLI 触发生成）
`~/.claude/mcp.json`	可选	纯 MCP 定义拆分，仅存储 `mcpServers` 节点	否（手动创建）

4.2 全局文件真实路径（全操作系统）

4.2.1 Windows 系统

plain 复制代码

%USERPROFILE%\.claude.json
%USERPROFILE%\.claude\settings.json
%USERPROFILE%\.claude\mcp.json

说明：%USERPROFILE% 对应 C:\Users\你的用户名（例：C:\Users\ZhangSan）。

4.2.2 macOS / Linux 系统

plain 复制代码

~/.claude.json
~/.claude/settings.json
~/.claude/mcp.json

说明：~ 代表用户家目录（macOS：/Users/你的用户名；Linux：/home/你的用户名）。

五、项目级配置（团队协作标准）

项目级配置仅对当前项目目录生效，核心用于团队协作，分为「共享配置」（团队共用）和「本地配置」（个人专用），边界清晰。

5.1 项目共享配置（提交 Git）

文件路径	核心作用	是否提交 Git
`项目根目录/.mcp.json`	定义项目专属 MCP 服务器（数据库、代码规范检查等）	是
`项目根目录/.claude/settings.json`	定义项目统一权限、环境变量默认值、MCP 启用开关	是

5.2 项目本地配置（不上 Git）

文件路径：项目根目录/.claude/settings.local.json

核心作用：存储个人本地覆盖配置、敏感信息（数据库密钥、API Token）、调试参数，临时覆盖项目共享配置。
关键特性：自动加入 .gitignore，不提交 Git，避免敏感信息泄露。

六、企业托管配置（普通用户可略过）

说明：该层级仅用于企业级管控，普通个人开发者、小型团队几乎不会接触，此处仅为内容完整客观说明。

6.1 核心作用

企业 IT 统一部署，用于强制安全策略、合规审计、内部 MCP 服务分发（如限制 MCP 白名单、禁用危险操作）。

6.2 系统路径（全操作系统）

6.2.1 Windows 系统

plain 复制代码

C:\ProgramData\ClaudeCode\managed-settings.json
C:\ProgramData\ClaudeCode\managed-mcp.json

6.2.2 macOS 系统

plain 复制代码

/Library/Application Support/ClaudeCode/managed-settings.json
/Library/Application Support/ClaudeCode/managed-mcp.json

6.2.3 Linux 系统

plain 复制代码

/etc/claude-code/managed-settings.json
/etc/claude-code/managed-mcp.json

6.3 核心特性

优先级最高，覆盖所有下层配置，普通用户无法修改、删除。
支持 allowedMcpServers（MCP 白名单）、deniedMcpServers（MCP 黑名单）。
用于企业全组织标准化部署，确保统一工具链与安全策略。

七、各配置文件完整内容示例（可直接复制）

所有示例遵循官方标准语法，无编造字段，可直接修改使用，规避新手踩坑。

7.1 全局 `.claude.json`（默认常用结构）

json 复制代码

{
  "auth": {
    "token": "xxx",
    "sessionId": "xxx"
  },
  "theme": "dark",
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "."
      ]
    },
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  },
  "permissions": {
    "allow": [
      "Read(**/*.{js,ts,json,md})",
      "Bash(git *)",
      "Bash(npm run *)"
    ],
    "deny": [
      "Read(.env)",
      "Read(.env.local)",
      "Read(**/*.pem)",
      "Read(**/*.key)"
    ]
  },
  "env": {
    "GITHUB_TOKEN": "ghp_xxxxxx",
    "MCP_TIMEOUT": "30000"
  },
  "enableAllProjectMcpServers": true
}

7.2 全局 `settings.json`（规则拆分版）

json 复制代码

{
  "permissions": {
    "allow": [
      "Read(**/*.{js,ts,json,md})",
      "Bash(git *)",
      "Bash(npm run *)"
    ],
    "deny": [
      "Read(.env*)",
      "Read(**/*.pem)",
      "Read(**/*.key)"
    ]
  },
  "env": {
    "GITHUB_TOKEN": "ghp_xxxxxx",
    "MCP_TIMEOUT": "30000"
  },
  "enableAllProjectMcpServers": true,
  "disabledMcpjsonServers": []
}

7.3 全局 `mcp.json`（纯 MCP 定义版）

json 复制代码

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
    },
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}

7.4 项目 `.mcp.json`（团队共享）

json 复制代码

{
  "mcpServers": {
    "project-db": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": { "DATABASE_URL": "${DATABASE_URL}" },
      "description": "项目开发数据库操作服务"
    },
    "eslint": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-eslint", ".eslintrc.js"],
      "description": "项目代码规范检查服务"
    }
  }
}

7.5 项目 `settings.json`（团队共享）

json 复制代码

{
  "permissions": {
    "allow": ["Bash(npm run lint)", "Bash(npm run build)"],
    "deny": ["Read(.env*)"]
  },
  "env": {
    "DATABASE_URL": "postgres://user:pass@localhost:5432/dev"
  },
  "enableAllProjectMcpServers": true
}

7.6 项目 `settings.local.json`（个人本地）

json 复制代码

{
  "env": {
    "DATABASE_URL": "postgres://local:local@localhost:5432/mydb",
    "LOCAL_DEBUG": "true"
  },
  "enabledMcpjsonServers": ["project-db"],
  "disabledMcpjsonServers": ["eslint"]
}

八、官方优先级规则（避坑关键）

以下为 Anthropic 官方明确定义的优先级规则，无任何虚构，直接决定配置生效逻辑：

高优先级配置直接覆盖低优先级，不深度合并（例：项目 MCP 服务替换全局同名服务）。
deny 权限不可逆：无论下层如何设置 allow，只要某一层级 deny，该操作即被禁止。
同一作用域文件优先级：settings.json ＞ mcp.json ＞ .claude.json。
跨作用域优先级：项目配置＞全局配置。
项目内部优先级：settings.local.json ＞项目共享配置。
企业托管配置优先级最高，覆盖所有其他层级。

九、MCP 标准字段完整说明（官方固定）

MCP 服务器配置遵循官方固定字段规范，以下重点说明最常用的 stdio（本地进程）和 http/sse（远程服务）类型。

9.1 stdio 类型（本地进程，最常用）

适用于本地运行的 MCP 服务（Node.js、Python、Go 等进程），字段示例及说明：

json 复制代码

{
  "type": "stdio",          // 传输类型，必选（固定为stdio）
  "command": "npx",         // 启动命令，必选
  "args": [],               // 命令参数，可选
  "env": {},                // 环境变量（存储密钥等），可选
  "cwd": "./",              // 工作目录（默认项目根目录），可选
  "timeout": 30000,         // 启动超时（毫秒），可选
  "disabled": false,        // 是否禁用（默认false），可选
  "description": ""         // 服务说明，可选
}

9.2 http / sse 类型（远程 MCP 服务）

适用于远程部署的 MCP 服务、云端服务，字段示例及说明：

json 复制代码

{
  "type": "http",           // 传输类型，必选（http/sse）
  "url": "https://xxx/mcp", // 服务地址，必选
  "headers": {},            // 请求头（身份认证等），可选
  "timeout": 60000,         // 请求超时（毫秒），可选
  "disabled": false         // 是否禁用（默认false），可选
}

十、最佳实践（可直接落地）

按用户层级提供对应方案，兼顾简洁性与规范性，避免冗余操作。

10.1 个人新手最简方案（推荐 90% 个人用户）

核心：仅使用官方自动生成的 ~/.claude.json，所有配置（MCP、权限、环境变量）写入该文件；项目级需求可临时创建 settings.local.json 覆盖。

10.2 进阶整洁方案（个人进阶用户）

核心：用模块化拆分文件提升可维护性------全局创建 ~/.claude/settings.json（管理规则）和 ~/.claude/mcp.json（管理 MCP 服务），将 .claude.json 对应配置迁移至这两个文件，保留基础信息。

10.3 团队标准方案（团队协作首选）

核心：项目共享配置（.mcp.json + .claude/settings.json）提交 Git，统一团队规范；个人本地配置（settings.local.json）存储敏感信息，不上传；全局仅配置跨项目通用 MCP 服务，避免冲突。

10.4 安全规范（必看）

安全配置核心：避免敏感信息泄露、防范误操作风险。

敏感信息（API Token、数据库密码）仅放入 settings.local.json，不写入可提交 Git 的文件。
filesystem MCP 仅开放当前项目目录，严禁开放系统根目录。
禁止全局允许 Exec(**) 或 Write(/*)，规避恶意操作。
定期清理无用 MCP 服务，减少攻击面。

十一、常见问题与避坑指南（新手必看）

结合官方文档，解答日常使用中最常见问题，规避新手弯路：

.claude.jsonsettings.jsonmcp.json 问题：仅存在，无和，正常吗？

复制代码

 解答：完全正常。后两个是可选拆分文件，官方不自动生成，需手动创建或 CLI 触发。

问题：配置修改后不生效？

复制代码

 解答：① 高优先级配置覆盖；② JSON 语法错误（多余逗号、括号不匹配），校验格式后重启 Claude Code 即可。

问题：MCP 启动提示"command not found"？

复制代码

 解答：`command` 字段命令未安装（如 `npx` 需安装 Node.js）或不在系统 PATH，安装依赖后重启。

问题：环境变量注入不生效？

复制代码

 解答：环境变量优先级：系统环境变量 ＞ `settings.local.json` ＞ `settings.json` ＞ `.claude.json`，检查是否有高优先级覆盖、变量名拼写是否一致。

问题：Windows 路径配置报错？

复制代码

 解答：路径需反斜杠转义，写成 `C:\\Users\\xxx` 或 `/C/Users/xxx`，避免单反斜杠语法错误。

十二、总结

Claude Code MCP 配置体系核心逻辑：「一个兜底主文件 + 两个模块化增强文件 + 项目级覆盖 + 企业级管控」，理解后配置将稳定、可预测、易维护。

全局 .claude.json：基础必备，自动生成，兜底兼容。
全局 settings.json/mcp.json：可选增强，提升模块化维护效率。
项目配置：团队协作核心，实现工程隔离与统一规范。
企业托管配置：系统级强制策略，个人用户可略过。

Claude Code教程（五）| MCP指南

Claude Code教程（五）| MCP指南

一、什么是 MCP

二、Claude Code 配置体系的历史演进

三、配置层级与官方优先级（真实且固定）

四、全局配置（用户级）完整文件体系

4.1 全局配置文件分类（必选+可选）

4.2 全局文件真实路径（全操作系统）

4.2.1 Windows 系统

4.2.2 macOS / Linux 系统

五、项目级配置（团队协作标准）

5.1 项目共享配置（提交 Git）

5.2 项目本地配置（不上 Git）

六、企业托管配置（普通用户可略过）

6.1 核心作用

6.2 系统路径（全操作系统）

6.2.1 Windows 系统

6.2.2 macOS 系统

6.2.3 Linux 系统

6.3 核心特性

七、各配置文件完整内容示例（可直接复制）

7.1 全局 .claude.json（默认常用结构）

7.2 全局 settings.json（规则拆分版）

7.3 全局 mcp.json（纯 MCP 定义版）

7.4 项目 .mcp.json（团队共享）

7.5 项目 settings.json（团队共享）

7.6 项目 settings.local.json（个人本地）

八、官方优先级规则（避坑关键）

九、MCP 标准字段完整说明（官方固定）

9.1 stdio 类型（本地进程，最常用）

9.2 http / sse 类型（远程 MCP 服务）

十、最佳实践（可直接落地）

10.1 个人新手最简方案（推荐 90% 个人用户）

10.2 进阶整洁方案（个人进阶用户）

10.3 团队标准方案（团队协作首选）

10.4 安全规范（必看）

十一、常见问题与避坑指南（新手必看）

十二、总结

7.1 全局 `.claude.json`（默认常用结构）

7.2 全局 `settings.json`（规则拆分版）

7.3 全局 `mcp.json`（纯 MCP 定义版）

7.4 项目 `.mcp.json`（团队共享）

7.5 项目 `settings.json`（团队共享）

7.6 项目 `settings.local.json`（个人本地）