AI导哈

Codex CLI MCP桥接工具

一个将OpenAI Codex CLI桥接到任何MCP客户端的工具，支持在无头模式下运行Codex CLI会话。

  • by nayagamez
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 nayagamez/codex-cli-mcp

使用说明

将OpenAI Codex CLI桥接到任何MCP客户端

英语| 韩语

npm · GitHub · 问题

概述

包装的MCP（模型上下文协议）服务器 OpenAI Codex命令行界面 作为工具。它使MCP客户端能够像 克劳德桌面版, 光标，以及 帆板运动 以无头模式运行Codex CLI会话。

先决条件

1.安装Codex CLI

安装 Codex 命令行界面 (文档)并确保它在您的PATH中可用：

# npm
npm install -g @openai/codex

# Homebrew (macOS)
brew install --cask codex

或者从以下网址下载二进制文件 GitHub发布.

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, max （根据任务复杂性自动选择）
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, max （根据任务复杂性自动选择）
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
  1. MCP客户端发送工具调用(codex 或 codex-reply)
  2. 服务器生成Codex CLI --json 和 --full-auto 旗帜
  3. 提示通过stdin传递
  4. JSONL事件实时流式传输和解析
  5. 每个事件都会向客户端发送进度通知（空闲定时器重置）
  6. 结果（消息、命令、错误、令牌使用）被格式化为markdown并返回

许可证

麻省理工学院

相关 MCP