崔怂包MCP.json 配置完整教程与实战示例
写代码的时候，我越来越依赖 Claude Code、Cursor 这类 AI 编程工具。用得越深，越发现一个绕不开的坎：AI 只能“看”，不能“动”。它帮你翻项目文件、跑测试、查数据库，靠的是一套叫 MCP 的外部工具协议，而 mcp.json 就是那本“通讯录”，告诉 AI 工具该去哪里调服务。今天专门把这份配置文件的写法和实战经验整理出来，填上文档没写清楚的那些坑。
这套配置的受众很明确：在用或用过 Claude Code、Cline、Windsurf、Cursor 等支持 MCP 的 AI 编程工具，想让 AI 真正操作真实环境的人。看完你至少能自己写出一份可运行的 mcp.json，遇到报错也知道从哪下手查。我会先从结构讲起，再给完整实战示例，最后是踩坑实录。
1. 先搞懂 MCP 和 mcp.json 之间的关系
1.1 MCP 到底解决什么问题
MCP 全称 Model Context Protocol，说人话就是：给 AI 模型开了一个“万能插头”。以前 AI 能力再强，也只能在你提供的文本上下文里绕圈，它不知道你本地磁盘上有什么文件、数据库里存了什么记录、GitHub 上哪个 Issue 还没关。MCP 协议把这个限制打破了——AI 可以通过一套标准化的消息格式，去调用外部工具，拿回真实世界的数据。
这就像给一个只会看菜单的人，配了一个能伸向后厨的手。菜单是对话，后厨是工具。MCP 服务器就是这个“手”，它负责把 AI 的请求翻译成具体的命令（比如读文件、查表、调 API），再把结果翻译回 AI 能懂的文本。
关键点是：所有 MCP 服务器的连接信息、启动参数、环境变量，都被统一写在一个 JSON 文件里，这个文件就是 mcp.json。你只需要告诉支持 MCP 的客户端“去加载这个文件”，它就能自动拉起一堆工具服务。
1.2 配置文件在项目里怎么放
mcp.json 的常见位置有三个，各有各的用途：
- 项目级：放在当前项目根目录，文件名也叫
.mcp.json（带点）或mcp.json。项目级配置只对当前项目生效，适合放这个项目专用的工具，比如数据库连接、项目独有的脚本。 - 用户级：放在用户主目录下，Claude Code 里默认是
~/.claude.json这类文件，对所有项目生效，适合放通用工具，比如文件系统、GitHub。 - 编辑器级：Cursor 和 VS Code 的 MCP 配置面板里可以单独加，等效于一个全局配置，只是入口在 GUI 界面里。
我个人的习惯是：全局要用的工具放用户级，项目专属的工具一律放到项目目录的 .mcp.json，这样 clone 下来新仓库时配置文件跟着走，团队成员直接就能用同一套工具，省去大量沟通成本。
1.3 为什么说它是 AI 工具链里的“基础设施”
如果只把 mcp.json 当成一个普通配置文件，你大概率会在某个奇怪的问题上卡上半小时。它本质上是一个进程编排文件：客户端会读取这个 JSON，然后按照里面的 command 自动启动子进程，再跟子进程建立标准输入输出的通信通道（stdio）。
所以配置里每一个字段都直接影响进程能不能正常启动、能不能连上。写错一个路径，AI 面板上显示的可能不是“启动失败”，而是幽怨地转圈然后提示超时。我一直建议把 mcp.json 当成“生产环境部署脚本”来对待，而不是随便填个命令试运气。这样心态对，后面遇到问题才不会慌。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. mcp.json 核心字段拆解，每个字符都要理解
2.1 找一个最小可运行的配置当模板
先看一个最基本、能立刻跑起来的例子：
json复制{
"mcpServers": {
"github": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-github"
],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
}
}
}
}
这个配置声明了一个叫 github 的 MCP 服务，用 npx 启动 GitHub 官方 MCP 包，然后传入了一个 GITHUB_PERSONAL_ACCESS_TOKEN 环境变量。看懂这三行，后面 90% 的配置都能举一反三。
顶层节点固定叫 mcpServers，你所有的服务都要挂在这个节点下面。每个服务是一个 key-value 结构，key 是服务名（自己起，要见名知意），value 是服务参数。
2.2 command、args、env、type 四个字段的角色
command：指定启动方式。最常见的有这几种：npx（N