开发者必看：三大 CLI 工具 MCP 配置详解

以下是三家 CLI 工具的 MCP 配置核心差异概述，后续章节将详细介绍每个工具的具体配置方式：

Gemini CLI ：使用 .gemini/settings.json（项目级）和 ~/.gemini/settings.json（用户级），通过 mcpServers 与 mcp 统一管理
Codex CLI ：使用 .codex/config.toml（项目级，逐层加载）和 ~/.codex/config.toml（用户级）
Claude Code ：使用 .mcp.json（项目级）和 ~/.claude.json（用户级），支持 local/project/user 三个作用域

Gemini CLI（google/gemini-cli）

配置位置

项目级 ：.gemini/settings.json
用户级 ：~/.gemini/settings.json

常用命令

bash 复制代码

gemini mcp add/list/remove # 默认 project 作用域
gemini mcp add <server> -s/--scope user # 指定 user 作用域

配置结构示例

项目级配置（.gemini/settings.json）

json 复制代码

{
  "mcpServers": {
    "team-server": {
      "type": "http",
      "url": "https://mcp.example.com",
      "headers": {
        "Authorization": "Bearer {{TOKEN}}"
      }
    }
  },
  "mcp": {
    "allow": ["*.example.com"],
    "exclude": ["node_modules/**"]
  }
}

用户级配置（~/.gemini/settings.json）

json 复制代码

{
  "mcpServers": {
    "personal-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["mcp-server", "--port", "3000"]
    }
  }
}

作用域与优先级

通过 settings.json 的 mcpServers 与 mcp 统一管理
gemini mcp add 支持 -s/--scope 参数，默认值为 project
项目级配置会覆盖用户级同名配置

Codex CLI（openai/codex）

配置位置与加载层级

Codex 使用 config.toml 文件，并按以下顺序层叠加载（优先级从高到低）：

运行时配置 ：通过 --config 等参数临时覆盖
项目层配置 ：从当前目录向上查找 .codex/config.toml，越接近当前目录优先级越高
用户层配置 ：$CODEX_HOME/config.toml（默认 ~/.codex/config.toml）

项目根目录识别

Codex 会基于 项目根 来确定搜索边界，默认以 .git 作为项目根标记。可在配置中改写 project_root_markers：

toml 复制代码

project_root_markers = [".git", ".codex-root", "package.json"]

常用命令

bash 复制代码

# 主要通过编辑 config.toml 文件
# OAuth 登录命令
codex mcp login <name>

配置结构示例

项目级配置（.codex/config.toml）

toml 复制代码

[mcp_servers.team-shared]
command = "npx"
args = ["-y", "mcp-server", "--env", "production"]

[mcp_servers.http-server]
url = "https://api.example.com/mcp"
bearer_token_env_var = "MCP_TOKEN"

用户级配置（~/.codex/config.toml）

toml 复制代码

[mcp_servers.personal-test]
command = "python"
args = ["-m", "mcp_server", "--debug"]

# 全局 MCP 设置
[mcp]
default_server = "team-shared"

作用域与优先级

配置按层叠顺序加载，越接近当前目录优先级越高
运行时配置 > 项目层配置 > 用户层配置
项目根目录默认以 .git 为界

Claude Code（claude-code）

配置位置

项目级 ：.mcp.json（建议纳入版本控制，团队共享）
用户级 ：~/.claude.json（跨项目共享）

常用命令

bash 复制代码

claude mcp add <server> --scope project # 项目级配置
claude mcp add <server> --scope user    # 用户级配置
claude mcp list --scope all             # 查看所有配置
claude mcp remove <server> --scope local # 移除本地配置

配置结构示例

项目级配置（.mcp.json）

json 复制代码

{
  "servers": {
    "team-mcp": {
      "type": "http",
      "url": "https://mcp.team.example.com",
      "headers": {
        "X-Team": "engineering"
      }
    }
  },
  "default": "team-mcp"
}

用户级配置（~/.claude.json）

json 复制代码

{
  "mcp": {
    "servers": {
      "personal-local": {
        "type": "stdio",
        "command": "npx",
        "args": ["mcp-server", "--port", "4000"]
      }
    },
    "local": {
      "current-project-id": {
        "servers": {
          "local-override": {
            "type": "http",
            "url": "http://localhost:3000"
          }
        }
      }
    }
  }
}

作用域与优先级

优先级顺序：local > project > user
local 作用域 ：存储在 ~/.claude.json 中，但仅对当前项目生效
项目级配置 ：通过 .mcp.json 文件共享，适合团队协作
用户级配置：跨项目共享，适合个人偏好设置

选择建议（按场景）

团队协作场景

优先使用项目级配置：把 MCP 服务器、权限、默认命令固定下来
将配置文件纳入版本控制，确保团队成员使用一致的设置
避免在项目级配置中存储敏感信息，可使用环境变量替代

个人习惯场景

使用用户级配置：承载个人路径、密钥与实验性配置
适合不同项目需要的个性化设置

配置覆盖场景

使用 local 作用域：在不修改团队配置的情况下，针对特定项目进行最小化覆盖
适合临时测试或本地开发需求

参考链接

Gemini CLI MCP 文档：https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md
Codex 配置文档：https://raw.githubusercontent.com/openai/codex/main/docs/config.md
Codex 配置加载逻辑（项目层级）：https://raw.githubusercontent.com/openai/codex/main/codex-rs/core/src/config_loader/mod.rs
Claude Code MCP 文档：https://code.claude.com/docs/en/mcp