最近在折腾Claude Code,发现十个配置问题里有八个都出在MCP.json上。要么是服务器没起来,要么是环境变量没传进去,要么是项目级配置和全局配置互相打架。这篇文章把我这段时间踩过的坑、验证过能跑通的写法、以及排查思路完整整理出来,希望能帮你少走弯路。
MCP(Model Context Protocol)这个词现在基本是AI编程工具链的标配了。无论你用Claude Code、Claude Desktop还是其他支持MCP协议的客户端,最终都要面对这个叫MCP.json的配置文件。搞懂了它,就等于掌握了给AI接电源插座的方法:你想让它读文件、操作数据库、调GitHub,都靠这个文件里的一条条服务器声明。
文章不会只贴一个配置样例就完事。我会从协议本身讲起,再逐字段拆解,然后给四个可以直接抄作业的实战示例,最后附上完整的排查链路。无论你是第一次接触MCP,还是已经在用但总被配置问题卡住,这篇都值得花十分钟仔细看完。
1. 先搞清楚MCP.json到底是干什么的
1.1 MCP协议在解决什么问题
传统上,让AI大模型访问外部数据或者执行操作,只有一条路:在提示词里粘贴文本让它"看"。比如你复制一段日志丢给模型,让它分析报错原因。但这种方式根本没法处理动态数据,更不可能让模型直接调API、查数据库、操作本地文件。
MCP协议想解决的就是这个割裂问题。它把AI应用和外部工具系统之间的连接标准化了。你可以把MCP理解成一个USB-C接口——原来每个工具都得配一根专属线缆,现在统一了接口标准,插上就能通。
具体到架构上,MCP有客户端(Client)和服务器(Server)两端。AI应用(比如Claude Code)是客户端,负责跟用户对话、理解意图。MCP服务器是执行方,负责提供具体能力,比如文件读写、GitHub操作、数据库查询。两端通过标准协议通信,而MCP.json就是客户端用来记录"有哪些服务器、怎么连接它们"的注册表。
1.2 MCP.json在Claude Code生态中的坐标
很多教程一上来就让你改配置,却不解释这个文件在整套工具链里处于什么位置。弄清楚坐标,后续排错会轻松很多。
在Claude Code里,MCP配置分三个层级,优先级从高到低分别是:
- 项目级配置文件
.mcp.json,放在项目根目录,只对当前项目生效,可以提交到Git仓库给团队共享。 - 用户级配置
~/.claude.json,属于当前系统用户,对所有项目生效,但不会提交到仓库。 - 命令行动态注册,通过
claude mcp add添加的服务器,同样存储在用户级配置里。
实际使用中,我个人的习惯是:跟项目强相关的工具(比如这个项目专用的数据库连接、本地服务路径)放项目级 .mcp.json;跟个人工作流强相关的工具(比如通用的文件系统读写、GitHub令牌)放用户级配置。
1.3 配置文件到底放在哪:三个常见位置
这是初学者最容易懵的地方。不同客户端、不同版本,配置文件位置不一样,网上教程又各说各话,搞得人一头雾水。
以Claude Code为例,常见的有这么几个位置:
- 项目级:项目根目录下的
.mcp.json - 用户级:
~/.claude.json里的mcpServers字段 - Claude Desktop:
~/Library/Application Support/Claude/claude_desktop_config.json(macOS)或%APPDATA%\Claude\claude_desktop_config.json(Windows)
我曾在项目根目录建了 .mcp.json,结果发现Claude Code根本没读取,后来才意识到我把文件命名成了 .mcp.json.example,就差一个后缀。如果你配置了半天发现完全不生效,第一件事就是确认文件名和位置对吗。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 配置文件逐字段拆解:每个键值背后的设计意图
2.1 command与args:如何正确拉起本地进程
本地MCP服务器最常见的传输方式是stdio,也就是客户端直接以子进程方式启动服务器程序。这个启动指令就由 command 和 args 两个字段决定。
json复制{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/me/projects"
]
}
}
}
command 填的是可执行文件名或完整路径。填可执行文件名时,客户端会去系统PATH里找这个命令。这里有
