command 写完整路径还是只写命令名？

如果命令在系统 PATH 中，写命令名即可（如 "npx"）。如果使用 nvm 等版本管理器，PATH 可能不包含该命令，此时需要写完整路径（如 "/Users/name/.nvm/versions/node/v20.0.0/bin/npx"）。

args 中的路径可以用波浪号（~）吗？

取决于 Server 的实现。大多数情况下建议使用绝对路径，因为波浪号展开是 Shell 的功能，而 MCP Server 通常不经过 Shell 启动。

env 中设置的变量会覆盖系统环境变量吗？

是的，env 中的变量会覆盖同名的系统环境变量，但仅对该 Server 进程生效。

MCP 配置 JSON 字段说明 - AI Agent 与 MCP Server 工具目录

配置文件结构

一个典型的 MCP 配置文件结构如下：

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"],
      "env": {
        "API_KEY": "your-key-here"
      }
    }
  }
}

字段详解

mcpServers（顶层对象）

包含所有 MCP Server 配置的容器。每个键是 Server 的标识名（自定义），值是该 Server 的配置对象。

command（必填）

启动 MCP Server 的可执行命令。常见值：

"npx" - 运行 npm 包（Node.js 生态的 Server）
"uvx" - 运行 Python 包（Python 生态的 Server）
"node" - 直接运行 Node.js 脚本
"python" - 直接运行 Python 脚本
"docker" - 通过 Docker 容器运行

注意：command 必须在系统 PATH 中可找到，或者使用完整路径。

args（必填）

传递给 command 的参数数组。每个参数是一个独立的字符串元素：

// 正确写法：每个参数独立
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/name/docs"]

// 错误写法：不要把多个参数合并为一个字符串
"args": ["-y @modelcontextprotocol/server-filesystem /Users/name/docs"]

env（可选）

传递给 Server 进程的环境变量。用于提供 API Key、Token 等敏感配置：

"env": {
  "GITHUB_TOKEN": "ghp_xxxxxxxxxxxx",
  "API_BASE_URL": "https://api.example.com"
}

这些环境变量只对该 Server 进程可见，不会影响系统环境。

常见配置模式

npx 运行 npm 包

{
  "command": "npx",
  "args": ["-y", "package-name", "arg1", "arg2"]
}

-y 参数表示自动确认安装，避免交互式提示阻塞启动。

uvx 运行 Python 包

{
  "command": "uvx",
  "args": ["package-name", "--option", "value"]
}

uvx 是 uv 工具链的一部分，需要先安装 uv：curl -LsSf https://astral.sh/uv/install.sh | sh

Docker 运行

{
  "command": "docker",
  "args": ["run", "-i", "--rm", "image-name:tag"]
}

注意必须包含 -i（交互模式）以保持 stdio 通信。

注意事项

JSON 格式要求严格：键名必须用双引号，末尾不能有多余逗号。
Windows 路径中的反斜杠需要转义："C:\\Users\\name"。
Server 标识名（键名）建议使用小写字母和连字符，如 "github-server"。
env 中的值必须是字符串类型，即使是数字也要加引号。
不要把真实的 API Key 提交到公开仓库。

常见问题

command 写完整路径还是只写命令名？: 如果命令在系统 PATH 中，写命令名即可（如 "npx"）。如果使用 nvm 等版本管理器，PATH 可能不包含该命令，此时需要写完整路径（如 "/Users/name/.nvm/versions/node/v20.0.0/bin/npx"）。
args 中的路径可以用波浪号（~）吗？: 取决于 Server 的实现。大多数情况下建议使用绝对路径，因为波浪号展开是 Shell 的功能，而 MCP Server 通常不经过 Shell 启动。
env 中设置的变量会覆盖系统环境变量吗？: 是的，env 中的变量会覆盖同名的系统环境变量，但仅对该 Server 进程生效。

MCP 配置 JSON 字段说明