Codex CLI MCP 入门指南：连接外部数据与服务
入门15 分钟阅读
Codex CLI MCP 入门指南：连接外部数据与服务

Codex CLI MCP 入门指南：连接外部数据与服务

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

学习目标

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

  • 用通俗的语言解释 MCP（模型上下文协议）是什么
  • 寻找能将 Codex 连接到外部数据和服务的 MCP 服务器
  • 使用 codex mcp add 命令为 Codex CLI 添加 MCP 服务器
  • 验证 MCP 服务器是否已连接并正常工作
  • 在对话中让 Codex 调用 MCP 工具

预计用时： 15–20 分钟

难度： 初级

本篇覆盖哪个版本？ 本教程覆盖 Codex CLI——Codex 的命令行版本。MCP 服务器通过 codex mcp 命令和 ~/.codex/config.toml 文件配置。如果你需要桌面版，请阅读 Codex 桌面客户端安装与首次使用指南。

前置条件

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

要求说明
已安装 Codex CLI运行 codex --version 应显示版本号。未安装？请先阅读 Codex CLI 入门指南
已登录 Codex运行 codex 并用 ChatGPT 账户或 API key 登录
Node.js（部分服务器需要）某些 MCP 服务器通过 npx 运行——从 nodejs.org 下载 LTS 版本
待连接的 MCP 服务器本教程示例：GitHub 或简单的本地服务器

什么是 MCP？

MCP（Model Context Protocol，模型上下文协议）是一种开放标准，让 Codex 等 AI 助手能够连接到外部数据和服务。可以把它想象成一个通用插头——每个工具不需要自己构建定制集成，大家用同一个协议沟通。

MCP 服务器是一个小程序，向 AI 助手暴露工具、数据或服务。例如：

  • GitHub MCP 服务器让 Codex 读取 Issue、创建 Pull Request、浏览仓库
  • 数据库 MCP 服务器让 Codex 用自然语言查询你的数据库
  • 搜索 MCP 服务器让 Codex 搜索网络并返回实时结果

当添加 MCP 服务器后，Codex 在对话中会自动调用它的工具——无需手动复制粘贴数据。

Codex MCP 的工作原理

Codex CLI 内置了 MCP 支持，分为两个方向：

  1. 1Codex 连接 MCP 服务器（本教程重点）——用 codex mcp add 添加服务器，Codex 在对话中可使用其工具
  2. 2其他工具连接 Codex——codex mcp-server 命令将 Codex 暴露给其他 MCP 客户端（高级用法，在 FAQ 简要提及）

配置存储在 ~/.codex/config.toml 的 [mcp_servers.*] 区域。codex mcp 命令会自动编辑此文件。

第 1 步：检查 MCP 设置

首先确认你的 Codex CLI 支持 MCP。打开终端并运行：

bash
codex mcp list

你应该看到： 提示"未配置 MCP 服务器"（或已有服务器列表）。如果命令不可识别，请更新 Codex CLI：

bash
npm install -g @openai/codex

你应该看到： 更新完成后显示版本号。

第 2 步：寻找 MCP 服务器

MCP 服务器可在多处找到：

  • 站内 MCP 目录：浏览 /mcp——55+ 款精选 MCP 服务器，涵盖 GitHub、Figma、数据库等
  • GitHub：搜索 mcp-server——有数千个社区服务器
  • npm：许多服务器可通过 npx 安装

本教程连接 GitHub 官方账号的 **GitHub MCP 服务器**——Cataito 收录的 55+ 款 MCP 服务器之一。

如果你偏好其他服务（Figma、Slack、数据库），使用相同的 codex mcp add 命令即可——只需替换服务器名称和命令。

第 3 步：添加 MCP 服务器（macOS 和 Linux）

在 macOS 或 Linux 上，打开终端并注册 GitHub MCP 服务器：

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

你应该看到： 命令无错误完成，Codex 将服务器条目写入 ~/.codex/config.toml。

第 3 步：添加 MCP 服务器（Windows）

在 Windows 上，打开 PowerShell 并注册 GitHub MCP 服务器：

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

你应该看到： 命令无错误完成，Codex 将服务器条目写入配置文件（%USERPROFILE%\.codex\config.toml）。

第 4 步：验证服务器已连接

确认服务器已正确注册：

bash
codex mcp list

你应该看到： github 出现在已配置的 MCP 服务器列表中。

你也可以查看单个服务器的详情：

bash
codex mcp get github

你应该看到： 服务器详情，包括 Codex 启动它时使用的命令。

第 5 步：在对话中使用 MCP 工具

现在启动 Codex 会话，让它使用 GitHub 工具：

bash
codex

然后输入一个利用已连接服务的提示，例如：

code
列出 facebook/react 仓库中的开放 Issue

你应该看到： Codex 自动调用 GitHub MCP 服务器的工具，获取数据并为你总结。一旦服务器添加完成，MCP 工具在每个会话中都可使用——无需额外配置。

第 6 步：移除或禁用服务器（可选）

如果不再需要某个服务器，移除它：

bash
codex mcp remove github

你应该看到： 该服务器从 codex mcp list 的列表中消失。

要保留条目但阻止 Codex 加载它，在 ~/.codex/config.toml 中在该行开头添加 # 注释掉。

排查问题

问题原因解决方法
codex: command not found未安装 Codex CLI安装：npm install -g @openai/codex，然后重启终端
mcp 不是有效子命令Codex CLI 版本过旧更新：npm install -g @openai/codex
url is not supported for stdio 错误服务器条目使用 HTTP 传输但缺少传输类型编辑 ~/.codex/config.toml，在该服务器区域添加 transport = "streamable_http"，或删除条目后重新添加
MCP 服务器启动但工具失败服务器需要 API key 或 token查看服务器 README 了解所需的环境变量（如 GITHUB_TOKEN），设置后重启 Codex
npx: command not found未安装 Node.js从 nodejs.org 安装 Node.js LTS，然后重启终端
首次调用时服务器超时首次运行需下载包稍等片刻后重新尝试提示

常见问题

使用 MCP 需要付费计划吗？ 不需要。MCP 支持是 Codex CLI 的一部分，ChatGPT 计划和 API key 认证都可使用。

可以用不同型号使用 MCP 服务器吗？ 可以——无论 Codex 使用哪种模型，MCP 工具都可用。

MCP 配置存储在何处？ 在 ~/.codex/config.toml（macOS/Linux）或 %USERPROFILE%\.codex\config.toml（Windows）的 [mcp_servers.*] 区域。

可以为单个项目添加服务器吗？ 可以——较新版本的 Codex 支持 codex mcp add --scoped <名称> -- <命令> 将服务器写入项目的 .codex/config.toml 而非全局配置。

其他工具可以通过 MCP 使用 Codex 吗？ 可以——运行 codex mcp-server 将 Codex CLI 暴露为 MCP 服务器，供其他 MCP 客户端（如 Claude Code 或 Cursor）使用。这是高级用法，详见 Codex 文档。

下一步

#Codex#MCP#Integrations
返回教程

相关教程