使用说明

codex mcp

codex-mcp 是一个基于Go的MCP stdio服务器，它封装了OpenAI的Codex CLI并公开了 codex exec 作为一个名为的结构化MCP工具 codex_exec.

它建立在官方模型上下文协议Go SDK 并且用于代理工作流，其中诸如Claude Code之类的MCP客户端需要将自包含的编码任务委托给Codex，接收最终的辅助消息，并在可预测的模式中捕获执行元数据。

特性

显示两个结构化MCP工具： codex_exec 和 codex_list_models
让调用模型每次运行时选择Codex模型，并通过以下方式进行实时发现 codex_list_models （支持 codex debug models)
让调用模型选择每次运行的推理工作量(reasoning_effort)，每个型号支持的级别由以下人员报告 codex_list_models
发布MCP工具注释(readOnlyHint, destructiveHint, openWorldHint)因此，客户端可以适当地呈现和引导工具调用
通过stdio运行，可以轻松插入本地MCP客户端
使用JSONL事件解析包装Codex非交互式执行
从以下内容中提取表面Codex故障原因（例如不受支持的型号、使用限制） error / turn.failed 事件
支持通过以下方式恢复现有的Codex线程 thread_id
强制使用允许的工作区根目录以及可选的其他允许目录
在执行之前规范化路径并解析符号链接
自动启用 --skip-git-repo-check 当目标目录不是Git存储库时
使用可配置的信号量限制并发Codex运行
支持YAML配置和CLI标志覆盖
将结构化JSON日志发送到stderr

需求

转到1.26或更高版本从源代码构建/安装
这个 codex CLI已安装并可用于 PATH，或明确配置为 --codex-bin
运行服务器的计算机上的工作Codex身份验证/会话

安装

使用Go直接安装服务器：

go install github.com/denysvitali/codex-mcp/cmd/codex-mcp@latest

然后验证它是否可用：

codex-mcp version

配置

codex-mcp 从以下位置读取YAML配置文件 ~/.config/codex-mcp/config.yaml 默认情况下，当该文件存在时。CLI标志覆盖文件值。

YAML配置

例子：

codex_bin: codex
root: /path/to/workspace
allow_dirs:
  - /path/to/extra-worktree
allow_models:
  - gpt-5.4-mini
  - gpt-5.4

default:
  yolo: true
  model: gpt-5.4-mini
  reasoning_effort: medium
  sandbox: workspace-write

max_concurrent_runs: 4
log_level: info

配置字段

字段	类型	描述
`codex_bin`	string	Codex CLI二进制文件的路径。默认为 `codex`.
`root`	string	允许的主要工作区根。如果省略，服务器将在启动时回退到当前工作目录。
`allow_dirs`	字符串列表	允许的其他目录 `cwd` 决心
`allow_models`	字符串列表	限制调用者可以传递给哪个模型slug `codex_exec`. `codex_list_models` 然后只报告这些模型。默认为空，这允许使用完整的目录。
`default.yolo`	bool	默认情况下是否在无限制模式下运行Codex。默认为 `true`.
`default.model`	string	当请求未指定模型时，传递给Codex的默认模型。默认为空，这允许Codex CLI选择自己的默认模型。
`default.reasoning_effort`	string	请求未指定推理时的默认推理努力（例如。 `low`, `medium`, `high`, `xhigh`).默认为空，这将使用模型自己的默认值。
`default.sandbox`	string	沙盒在以下情况下使用 `default.yolo` 是 `false`.有效值： `read-only`, `workspace-write`, `danger-full-access`.
`max_concurrent_runs`	integer	一次允许的最大Codex进程数。默认为 `4`.
`log_level`	string	Logrus级别。有效值包括 `error`, `warn`, `info`, `debug`, `trace`.默认为 `info`.

CLI标志

服务器可以完全通过标志进行配置：

codex-mcp serve \
  --root /path/to/workspace \
  --allow-dir /path/to/extra-worktree \
  --allow-model gpt-5.4-mini --allow-model gpt-5.4 \
  --codex-bin /usr/local/bin/codex \
  --default-yolo=false \
  --default-sandbox workspace-write \
  --default-model gpt-5.4-mini \
  --default-reasoning-effort medium \
  --max-concurrent-runs 2 \
  --log-level info

可用标志：

标志	描述
`--codex-bin`	Codex二进制文件的路径
`--root`	允许的主要工作区根
`--allow-dir`	额外允许的目录；可重复
`--allow-model`	限制呼叫者只能使用此型号的slug；可重复或逗号分隔（空：所有目录模型）
`--config`	YAML配置文件的路径
`--default-yolo`	默认情况下启用无限制的Codex执行
`--default-model`	请求省略时的默认模型 `model` （空：Codex CLI自己的默认值）
`--default-reasoning-effort`	请求省略时的默认推理努力 `reasoning_effort` （空：模型自己的默认值）
`--default-sandbox`	禁用yolo时的默认沙盒
`--max-concurrent-runs`	最大并发Codex运行数
`--log-level`	记录冗长

用法

手动启动服务器

codex-mcp serve --root /path/to/workspace

服务器通过stdio进行通信，因此它通常由MCP客户端启动，而不是交互式使用。

Claude代码配置

Claude Code支持本地stdio MCP服务器。注册此服务器的一种简单方法是：

claude mcp add codex-mcp -- codex-mcp serve --root /path/to/workspace

您还可以添加等效的JSON配置。示例 .mcp.json 条目：

{
  "mcpServers": {
    "codex-mcp": {
      "type": "stdio",
      "command": "codex-mcp",
      "args": ["serve", "--root", "/path/to/workspace"],
      "env": {}
    }
  }
}

如果 codex-mcp 或 codex 不在 PATH，在命令中使用绝对路径并配置 --codex-bin 明确地。

MCP工具合同

服务器公开了两个工具：

codex_exec
codex_list_models

`codex_exec`

输入字段：

字段	必填	描述
`prompt`	是	已向食品法典委员会发送指示
`cwd`	否	运行的工作目录；从服务器根解析相对路径
`thread_id`	否	要恢复的现有Codex线程ID
`model`	没有	要运行的Codex模型。叫 `codex_list_models` 以发现可用的模型。默认为服务器默认模型。如果服务器设置 `allow_models`，任何其他模型都被拒绝
`reasoning_effort`	否	跑步的推理努力（例如。 `low`, `medium`, `high`, `xhigh`). `codex_list_models` 报告每个模型支持的级别。默认为服务器默认值
`profile`	否	根据请求Codex配置文件覆盖
`output_schema`	否	描述所需形状的JSON Schema对象 `final_message`
`add_dirs`	否	应与主工作区一起写入的其他目录。每个都必须位于服务器根目录内或已配置 `allow_dirs`.
`ephemeral`	否	运行时不保存会话文件；回归 `thread_id` 不应再次用于恢复。
`sandbox`	否	按请求沙盒覆盖，仅在服务器配置中禁用yolo时使用
`timeout_ms`	否	每次请求超时（毫秒）
`skip_git_repo_check`	否	覆盖自动Git存储库检测

输出字段：

字段	描述
`thread_id`	JSONL流中观察到的Codex线程ID
`final_message`	食品法典委员会返回的最终助理信息
`structured_output`	最终助手消息解析为JSON（当 `output_schema` 提供并且解析成功）
`usage`	令牌使用情况摘要
`elapsed_ms`	端到端执行时间
`exit_code`	进程退出代码
`raw_event_count`	从Codex输出解析的JSONL事件数
`stderr_tail`	显示一些错误路径以帮助诊断故障

当Codex运行失败时，工具错误包括失败原因Codex 在其事件流中报告（例如，不受支持的模型或用法 limit），因此调用模型可以做出反应，例如选择不同的建模并重试。

`codex_list_models`

不争论。返回本地Codex CLI模型通告的模型目录(codex debug models)，按照食品法典委员会自己的优先顺序排序，加上服务器的有效默认模型。

输出字段：

字段	描述
`models`	可用型号列表，每种型号都有 `slug`, `display_name`, `description`, `default_reasoning_level`，以及 `supported_reasoning_levels`
`default_model`	使用的模型 `codex_exec` 当请求省略时 `model`；空表示Codex CLI选择自己的默认值
`default_reasoning_effort`	推理工作由以下人员使用 `codex_exec` 当请求省略时 `reasoning_effort`；空表示模型自身的默认值

传递模型 slug 随着 model 论点 codex_exec，其中之一 supported_reasoning_levels 作为 reasoning_effort.

架构概述

代码库有意地很小，并分成几个重点包：

cmd/codex-mcp/main.go 定义Cobra CLI，加载配置，验证运行时设置，并启动stdio MCP服务器。
internal/config/config.go 处理YAML加载、默认值、路径规范化和配置验证。
internal/mcpserver/server.go 在官方网站上定义MCP服务器 modelcontextprotocol/go-sdk，注册 codex_exec 和 codex_list_models，验证工具输入，并将MCP调用映射到运行器请求。
internal/codexcli/runner.go 构建 codex exec 命令，执行目录限制，管理超时和并发，解析JSONL输出，并返回结构化结果。
internal/codexcli/models.go 通过解析来发现可用的Codex模型 codex debug models 目录。
internal/codexcli/git.go 执行Git存储库检测，用于 --skip-git-repo-check.

运行时，流程为：

MCP客户端启动 codex-mcp 超过stdio。
codex-mcp 加载配置，解析允许的根，并检查Codex二进制文件是否存在。
MCP客户端调用 codex_exec.
服务器验证输入并将请求转发给运行者。
跑步者决心 cwd 以及任何 add_dirs，确保它们保持在允许的目录内，构造 codex exec 命令，并执行它。
跑步者写道 -o <tempfile> 因此，如果JSONL解析没有返回，它可以使用最终的辅助消息作为回退 item.completed 与 agent_message，然后将JSONL输出解析为结构化的MCP工具结果。

安全考虑

此项目执行一个本地编码代理，应在部署时考虑约束。

目录访问权限仅限于 root 和 allow_dirs，在执行之前解析符号链接，以防止简单的路径转义技巧。
模型使用可以通过以下方式进行限制 allow_models / --allow-model：在Codex开始之前，命名任何其他型号的请求都会被拒绝，以及 codex_list_models 只宣传允许的蛞蝓。A已配置 default.model 启动时拒绝允许列表之外的请求。
相对的 cwd 值是从配置的根目录解析的，而不是从调用者的任意当前目录解析的。
并发的Codex运行受到以下限制 max_concurrent_runs 以减少资源争用。
默认配置启用yolo模式(default.yolo: true)，这与食品法典委员会的无限制绕过标志相对应。这很方便，但比沙盒执行限制性要小得多。
如果你想要更强的隔离，设置 default.yolo: false 并使用显式沙盒，例如 workspace-write 或 read-only.
服务器向stderr发送日志，包括任务元数据和失败上下文。避免将日志发送到不应接收工作区路径或错误输出的目标。
服务器运行任何东西 codex 二进制你指向它。处理 codex_bin 作为您值得信赖的计算基础的一部分。

许可证

此存储库当前不包括 LICENSE 文件。因此，许可条款没有在树中列出。

参考文献

官方模型上下文协议Go SDK：https://github.com/modelcontextprotocol/go-sdk
人类克劳德代码MCP文档：https://docs.anthropic.com/en/docs/claude-code/mcp

使用说明

codex mcp

特性

需求

安装

配置

YAML配置

配置字段

CLI标志

用法

手动启动服务器

Claude代码配置

MCP工具合同

codex_exec

codex_list_models

架构概述

安全考虑

许可证

参考文献

相关 MCP

网页抓取与搜索MCP服务器

Unity MCP AI游戏开发工具

用户名搜索MCP服务器

Jupyter笔记本MCP服务器

Python解释器服务

Claude Code开发工具包

`codex_exec`

`codex_list_models`