将OpenAI Codex CLI桥接到任何MCP客户端
英语| 韩语
npm · GitHub · 问题
______________________________________________________________________
概述
包装的MCP（模型上下文协议）服务器 OpenAI Codex命令行界面 作为工具。它使MCP客户端能够像 克劳德桌面版, 光标，以及 帆板运动 以无头模式运行Codex CLI会话。
先决条件
1.安装Codex CLI
# npm
npm install -g @openai/codex
# Homebrew (macOS)
brew install --cask codex或者从以下网址下载二进制文件 .
2.身份验证
选项A——ChatGPT登录（推荐）
跑 codex 然后选择“使用ChatGPT登录”。需要Plus、Pro、Team、Edu或Enterprise计划。
选项B-API密钥
对于无头/CI环境：
export OPENAI_API_KEY="your-api-key"请参阅 食品法典认证文件 了解更多详情。
工具
看 Codex模型 对于可用的型号。
codex
启动新的Codex CLI会话。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
prompt | string | Yes | 发送到Codex的提示 |
model | string | 否 | 模型名称覆盖 |
effort | enum | 否 | 推理努力： medium, high, xhigh （根据任务复杂性自动选择） |
sandbox | enum | 否 | read-only, workspace-write，或 danger-full-access |
cwd | string | 否 | 会话的工作目录 |
profile | string | 否 | 来自config.toml的配置文件 |
config | object | 否 | 配置重写为键值对 |
timeout | number | No | 超时（毫秒）（默认值： 600000 =10分钟） |
codex-reply
继续现有的Codex CLI会话。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
prompt | string | 是 | 后续提示 |
threadId | string | 是 | 以前的线程ID codex 呼叫 |
model | string | 否 | 模型名称覆盖 |
effort | enum | 否 | 推理努力： medium, high, xhigh （根据任务复杂性自动选择） |
config | object | 否 | 配置重写为键值对 |
timeout | number | No | 超时（毫秒）（默认值： 600000 =10分钟） |
设置
对于人类
复制下面的提示并将其粘贴到LLM代理中——它将自动安装和配置所有内容：
Install and configure @nayagamez/codex-cli-mcp by following: https://raw.githubusercontent.com/nayagamez/codex-cli-mcp/main/docs/guide/installation.md或者手动设置它——请参阅 手动设置 在......下面
LLM代理
curl -s https://raw.githubusercontent.com/nayagamez/codex-cli-mcp/main/docs/guide/installation.md手动设置
Claude Desktop
添加到您的 claude_desktop_config.json:
{
"mcpServers": {
"codex-cli-mcp": {
"command": "npx",
"args": ["-y", "@nayagamez/codex-cli-mcp"]
}
}
}Cursor / Windsurf
添加到MCP设置中：
{
"mcpServers": {
"codex-cli-mcp": {
"command": "npx",
"args": ["-y", "@nayagamez/codex-cli-mcp"]
}
}
}Claude Code
claude mcp add codex-cli-mcp -- npx -y @nayagamez/codex-cli-mcp进度通知
当Codex处理您的请求时，服务器会实时发送MCP进度通知。这让MCP客户端知道服务器处于活动状态并正常工作，而不是挂起。
进度信息包括：
[5s] Session started (thread: ...)--会话已初始化[12s] Command executed: npm test--运行了一个命令[18s] Message: Refactoring the auth module...--代理推理[25s] Turn completed--完成转弯
基于空闲的超时
超时时间为 基于空闲，不是绝对的。每次服务器从Codex接收到事件时，计时器都会重置。这意味着具有连续活动的长时间运行的任务永远不会超时，而真正卡住的进程将在配置的空闲期后被终止。
- 默认空闲超时： 10分钟
- 通过以下方式覆盖每次呼叫
timeout参数，或全局通过CODEX_TIMEOUT_MS
环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
CODEX_CLI_PATH | codex | Codex CLI二进制文件的路径 |
CODEX_TIMEOUT_MS | 600000 （10分钟） | Codex进程的空闲超时 |
CODEX_MCP_DEBUG | _（未设置）_ | 设置为启用stderr的调试日志记录 |
运作原理
MCP Client → Tool Call (codex / codex-reply)
→ Spawn `codex exec --json --full-auto` as subprocess
→ Stream JSONL events from stdout
→ Send progress notifications back to client
→ Return formatted results when done- MCP客户端发送工具调用(
codex或codex-reply) - 服务器生成Codex CLI
--json和--full-auto旗帜 - 提示通过stdin传递
- JSONL事件实时流式传输和解析
- 每个事件都会向客户端发送进度通知（空闲定时器重置）
- 结果（消息、命令、错误、令牌使用）被格式化为markdown并返回
许可证
麻省理工学院