第 3 卷

• **`${VAR_NAME}`** - 展开为环境变量 VAR_NAME 的值
• **`${VAR_NAME:-default_value}`** - 如果 VAR_NAME 未设置，使用默认值

#### 变量命名规则

• 变量名必须以大写字母或下划线 `[A-Z_]` 开头
• 后续字符只能是大写字母、数字或下划线 `[A-Z0-9_]*`
• 小写字母、混合大小写以及以数字开头的变量不会被展开

#### 支持的配置字段

环境变量可以在以下配置字段中展开：

**STDIO 类型配置**：

• `command` - 可执行文件路径或命令
• `args` - 命令行参数列表中的每个参数
• `env` - 环境变量值（键不会被展开）

**SSE/HTTP/Remote 类型配置**：

• `url` - 服务端点 URL
• `headers` - HTTP 请求头值（键不会被展开）

#### 错误处理

**环境变量未设置的行为**：

• 如果环境变量未设置且**有默认值**，使用默认值
• 如果环境变量未设置且**无默认值**，保留原始占位符（`${VAR}`），并在诊断中报告 WARNING 消息

这意味着配置不会因缺失的环境变量而失败，而是保留占位符并发出警告。

#### 示例配置

**示例 1：STDIO 类型服务器，使用环境变量** ```json { "mcpServers": { "python-tools": { "type": "stdio", "command": "${PYTHON_PATH:-python}", "args": [ "-m", "my_mcp_server", "--config", "${CONFIG_DIR:-/etc/config}"

], "env": { "PYTHONPATH": "${PYTHON_LIB_PATH}", "DEBUG": "${DEBUG_MODE:-false}", "API_KEY": "${API_KEY}"

}

示例 2：HTTP类型服务器，使用环境变量和默认值

json

{ "mcpServers": { "api-server": { "type": "http", "url": "${API_BASE_URL:-https://api.example.com}/mcp", "headers": { "Authorization": "Bearer ${API_TOKEN}", "X-API-Version": "${API_VERSION:-v1}", "User-Agent": "CodeBuddy/${CODEBUDDY_VERSION:-1.0}"

} } } }

常见用例

1.团队共享配置

bash

# 在 .mcp.json 中使用环境变量 # 每个团队成员在本地设置环境变量 export API_TOKEN="their-personal-token"

export LOCAL_TOOL_PATH="/home/user/tools"

2.环境特定配置

bash

# 开发环境 export API_BASE_URL="http://localhost:3000"

# 生产环境 export API_BASE_URL="https://api.production.com"

3.管理敏感信息

json

{ "headers": { "Authorization": "Bearer ${MY_API_KEY}"

将 API 密钥存储在环境变量中，不要直接写在配置文件中。

诊断和调试

当配置中的环境变量展开时，您可以通过以下方式了解展开结果：

1.如果某个环境变量未设置且无默认值，系统会发出 WARNING 诊断

2.可以通过 /mcp 命令查看 MCP 服务器配置和诊断信息

3.诊断消息会列出所有缺失的环境变量

示例诊断消息：

Missing environment variables: API_TOKEN, DATABASE_URL

配置结构详解

根据不同的传输类型，MCP 服务器配置具有不同的结构：

STDIO类型配置

通过标准输入输出与本地进程通信。

示例：

json

{ "type": "stdio", "command": "python", "args": ["-m", "my_mcp_server"], "env": { "PYTHONPATH": "/path/to/tools", "DEBUG": "true"