Codex 桌面客户端 MCP 指南：连接外部数据与服务
入门10 分钟阅读
Codex 桌面客户端 MCP 指南：连接外部数据与服务

Codex 桌面客户端 MCP 指南：连接外部数据与服务

CATAITO Team2026-08-08
你的操作系统:

学习目标

完成本教程后，你将能够：

  • 理解 MCP（模型上下文协议）在 Codex 桌面客户端中的工作方式
  • 通过配置文件为 Codex 桌面客户端添加 MCP 服务器
  • 在桌面客户端设置面板中启用和管理 MCP 服务器
  • 在 Codex 桌面会话中使用 MCP 工具

预计用时： 10–15 分钟

难度： 初级

本篇覆盖哪个版本？ 本教程覆盖 Codex 桌面客户端——Codex 的图形桌面应用。MCP 服务器通过 ~/.codex/config.toml 文件配置，该文件与 Codex CLI 共享。如果你使用命令行版本，请阅读 Codex MCP CLI 入门指南。

前置条件

开始之前，请确保已准备以下内容：

要求说明
已安装 Codex 桌面客户端打开 Codex 桌面客户端并确认能正常启动。未安装？请先阅读 Codex 桌面客户端安装与首次使用指南
已登录 Codex使用 ChatGPT 账户（Plus、Pro 或更高）登录
了解 MCP 基本概念如果你是 MCP 新手，请先阅读 Codex MCP CLI 入门指南 了解介绍

MCP 在 Codex 桌面客户端中的工作方式

Codex 桌面客户端与 Codex CLI 共享相同的 MCP 配置系统。所有 MCP 服务器都定义在 ~/.codex/config.toml（macOS/Linux）或 %USERPROFILE%\.codex\config.toml（Windows）文件中。

当你通过 CLI（codex mcp add）添加 MCP 服务器时，它会自动出现在 Codex 桌面客户端的 设置 → MCP 服务器 面板中。你也可以直接编辑 config.toml 文件。

与 CLI 版本的关键区别：

  • CLI：MCP 服务器在每个会话中都始终可用
  • 桌面客户端：MCP 服务器必须在设置面板中启用，部分情况下可能需要 OAuth 认证

第 1 步：打开 MCP 服务器设置

打开 Codex 桌面客户端并导航：

  1. 1点击侧边栏中的个人资料图标或设置齿轮
  2. 2在设置列表中选择MCP 服务器

你应该看到： 已配置的 MCP 服务器列表（如果尚未配置则为空列表）。每个服务器显示名称、状态和启用/禁用开关。

第 2 步：寻找 MCP 服务器

MCP 服务器可在多个地方找到。Cataito 收录了 55+ 款 MCP 服务器，可直接连接。本教程使用 **GitHub MCP 服务器**——最受欢迎的服务器之一，让 Codex 可以读取仓库、Issue 和 Pull Request。

在 Cataito 的 MCP 目录 浏览完整合集。

第 3 步：添加 MCP 服务器

有两种方式为 Codex 桌面客户端添加 MCP 服务器：

方式 A：使用 CLI（推荐）

如果你已安装 Codex CLI，打开终端添加服务器，它会自动出现在桌面客户端中：

bash
codex mcp add github -- npx -y @modelcontextprotocol/server-github

你应该看到： 服务器已注册。现在打开 Codex 桌面客户端，进入设置 → MCP 服务器——GitHub 服务器应出现在列表中（可能需要重启 Codex 桌面客户端）。

方式 B：直接编辑 config.toml

用文本编辑器打开 ~/.codex/config.toml（macOS/Linux）或 %USERPROFILE%\.codex\config.toml（Windows），添加服务器条目：

toml
[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]

保存文件，然后重启 Codex 桌面客户端。

你应该看到： 重启后 GitHub 服务器出现在设置 → MCP 服务器中。

第 4 步：启用 MCP 服务器

在设置 → MCP 服务器面板中：

  1. 1找到刚添加的服务器
  2. 2确保开关处于启用状态（绿色/开启）
  3. 3如果服务器需要 OAuth 认证，点击齿轮图标并按照认证流程操作

你应该看到： 服务器状态显示为"已连接"或"就绪"。

第 5 步：在桌面会话中使用 MCP 工具

现在在 Codex 桌面客户端中开始新对话并使用 MCP 工具：

  1. 1点击侧边栏中的新建对话
  2. 2输入使用 MCP 服务器的提示，例如：
code
列出 facebook/react 仓库中的开放 Issue

你应该看到： Codex 桌面客户端自动调用 GitHub MCP 服务器的工具，获取数据并在对话中显示结果。你也可以在对话中使用 /mcp 命令查看可用的 MCP 工具。

排查问题

问题原因解决方法
MCP 服务器出现在设置中但对话中不可用桌面客户端 bug：项目级服务器可能在 GUI 中不加载全局配置服务器（而非项目级），然后重启 Codex 桌面客户端
重启后服务器消失桌面客户端可能覆盖 config.toml用 codex mcp add 重新添加，或检查 ~/.codex/config.toml 是否损坏
OAuth 认证不显示桌面客户端 MCP 设置不显示每个服务器的 OAuth 状态先在 CLI 中认证：codex mcp login <服务器名称>，然后重启桌面客户端
对话中 MCP 工具不可用服务器可能在设置中被禁用进入设置 → MCP 服务器，确认开关已启用
npx: command not found未安装 Node.js从 nodejs.org 安装 Node.js LTS，然后重启 Codex 桌面客户端

常见问题

在桌面客户端使用 MCP 必须安装 Codex CLI 吗？ 不必。你可以直接编辑 config.toml，但推荐使用 codex mcp add，因为它能正确处理配置语法。

桌面客户端和 CLI 可以使用相同的 MCP 服务器吗？ 可以——它们共享同一个 ~/.codex/config.toml 文件。通过 CLI 添加的服务器会出现在桌面客户端中，反之亦然。

桌面版本支持所有 MCP 服务器吗？ 大多数基于 stdio 的 MCP 服务器可以工作。Streamable HTTP 服务器可能与桌面版本存在兼容性问题。

可以用免费 ChatGPT 计划使用 MCP 吗？ MCP 支持需要付费计划（Plus、Pro 或更高）。

下一步

#Codex#MCP#Desktop#Integrations
返回教程

相关教程