先确认配置保存在哪里#

Claude Code 支持项目级和用户级配置。项目级 .mcp.json 适合随项目共享（不要把密钥放进去）；个人配置则适合只在自己的环境使用。先按当前版本的官方说明确认文件名、配置结构和生效范围，不要把 Claude Desktop 的配置文件格式直接复制过来。

项目配置的结构大致如下，实际命令和参数要按 MCP 服务文档填写：

1
{
2
  "mcpServers": {
3
    "example": {
4
      "command": "npx",
5
      "args": ["-y", "some-mcp-server"]
6
    }
7
  }
8
}

保存前先检查 JSON 语法：属性名和字符串要用双引号，最后一项后面不要多逗号。Windows 路径中的反斜杠也容易造成转义问题；能用正斜杠时，配置会更容易读。

验证启动命令能在当前终端运行#

配置里的 command 必须能被 Claude Code 启动进程找到。先在同一个终端单独运行这个命令，确认运行时版本、包管理器和参数都正确。Windows 上如果交互式终端能找到 npx，但工具启动失败，可能是 GUI 启动环境的 PATH 不同；使用命令的绝对路径或统一启动环境来验证。

然后在 Claude Code 中检查 MCP 状态，例如运行 claude mcp list，并查看启动时的错误信息。常见原因包括包名或参数拼错、运行时未安装、服务器等待交互输入、启动后立即退出，以及工作目录或权限不符合预期。

如果服务器已经启动但工具仍不可用，逐项检查用户是否批准了该项目的 MCP 配置，以及工具是否被权限规则限制。修好配置后重新加载会话，再确认工具清单确实出现；不要把“配置文件存在”当作“服务器已连接”。

共享项目配置前要检查其中没有 API key、访问令牌或本机私有路径。MCP 服务器可能拥有文件或网络访问能力，只添加自己理解并信任的服务，并给它最小必要的目录范围。

参考：Claude Code MCP 文档