Gemini CLI MCP 配置中的 API Key 安全实践

在配置 Gemini CLI 连接远程 MCP 服务器时，一个常见的问题是如何安全地处理 API Key。很多远程 MCP 服务（如高德地图）需要在 URL 中传递密钥进行认证，直接将密钥硬编码在配置文件中显然不是好的做法。本文整理了几种推荐的安全处理方式。

背景

以高德地图 MCP 服务为例，官方提供的连接方式是：

https://mcp.amap.com/mcp?key=您在高德官网上申请的key

如果直接这样写在 ~/.gemini/settings.json 中：

{
  "mcpServers": {
    "amap": {
      "url": "https://mcp.amap.com/mcp?key=abc123xyz789"
    }
  }
}

这个配置文件可能会被纳入版本控制、备份到云端，或者在排查问题时被复制粘贴到各处，导致密钥泄露。

下面介绍几种在 Gemini CLI 中安全管理 API Key 的方法。

方案一：环境变量引用

Gemini CLI 支持在配置文件中使用 ${VAR_NAME} 语法引用环境变量，这是最推荐的方式。

首先，在系统环境中设置变量：

# 添加到 ~/.bashrc 或 ~/.zshrc
export AMAP_API_KEY="你的高德Key"

然后在配置文件中引用：

{
  "mcpServers": {
    "amap": {
      "url": "https://mcp.amap.com/mcp?key=${AMAP_API_KEY}"
    }
  }
}

Gemini CLI 启动时会自动将 ${AMAP_API_KEY} 替换为实际的环境变量值。这样配置文件中不包含任何敏感信息，可以安全地提交到版本控制。

方案二：使用 HTTP Headers 认证

如果 MCP 服务端支持通过 HTTP Header 进行认证（而不是 URL 参数），这种方式比 URL 参数更安全，因为 Header 不会出现在日志、浏览器历史或缓存中。

{
  "mcpServers": {
    "my-mcp-server": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "X-API-KEY": "${MY_API_KEY}"
      }
    }
  }
}

需要注意的是，这要求服务端支持 Header 认证。高德地图 MCP 目前只支持 URL 参数方式，但其他一些 MCP 服务可能支持这种更安全的认证方式。

方案三：本地 Stdio 代理

对于本地进程类型的 MCP 服务器，可以通过 env 字段注入环境变量，完全避免在网络 URL 中暴露密钥：

{
  "mcpServers": {
    "amap-maps": {
      "command": "npx",
      "args": ["-y", "@amap/amap-maps-mcp-server"],
      "env": {
        "AMAP_MAPS_API_KEY": "${AMAP_API_KEY}"
      }
    }
  }
}

这种方式下，密钥只存在于本地进程的环境变量中，不会通过网络传输。

三种传输方式的安全特点

Gemini CLI 支持三种 MCP 传输机制，安全性各有不同：

Stdio（本地进程）

最安全的方式。密钥只存在于本地进程环境中，不经过网络：

{
  "mcpServers": {
    "local-server": {
      "command": "python",
      "args": ["-m", "my_mcp_server"],
      "env": {
        "API_KEY": "$EXTERNAL_API_KEY"
      }
    }
  }
}

SSE / HTTP（远程服务）

需要特别注意密钥的处理。优先使用 Header 认证，其次使用环境变量引用：

{
  "mcpServers": {
    "remote-server": {
      "url": "https://api.example.com/sse",
      "headers": {
        "Authorization": "Bearer ${MY_TOKEN}"
      }
    }
  }
}

OAuth 认证

对于支持 OAuth 的 MCP 服务，Gemini CLI 提供了自动化的认证流程：

自动检测 401 响应，判断是否需要 OAuth 认证
在浏览器中打开认证流程
将令牌安全存储在 ~/.gemini/mcp-oauth-tokens.json
自动管理令牌刷新

这种方式下，不需要在配置文件中存储任何密钥，认证令牌由 CLI 自动管理。

可以通过 /mcp auth 命令查看和管理 OAuth 认证状态。

完整配置示例

结合以上实践，一个安全的 MCP 配置可能是这样的：

{
  "mcpServers": {
    "amap": {
      "url": "https://mcp.amap.com/mcp?key=${AMAP_API_KEY}"
    },
    "github": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}"
      }
    },
    "local-tools": {
      "command": "node",
      "args": ["./mcp-server/index.js"],
      "env": {
        "DB_PASSWORD": "${DB_PASSWORD}"
      }
    }
  }
}

对应的环境变量设置：

# ~/.bashrc 或 ~/.zshrc
export AMAP_API_KEY="your-amap-key"
export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"
export DB_PASSWORD="your-db-password"

总结

在 Gemini CLI 中配置 MCP 服务器时，API Key 的安全处理是一个容易被忽视但很重要的问题。核心原则很简单：配置文件中不应该包含任何明文密钥。通过环境变量引用、Header 认证、本地代理等方式，可以在保持配置灵活性的同时确保密钥安全。

对于支持 OAuth 的服务，优先使用 OAuth 认证，让 CLI 自动管理令牌生命周期。对于只支持 API Key 的服务，务必使用环境变量而不是硬编码。

参考

Gemini CLI MCP Server 文档