How do I use codex-mcp-server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@codex-mcp-server review the code in src/utils/ for best practices" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

codex-mcp-server

MCP server for Codex CLI — tmux persistence, git worktree isolation, async dispatch.

English | 简体中文

特性

tmux 持久化 — full-access 任务运行在 tmux session 中，网络断开、窗口关闭后任务继续执行；read-only 任务直接 subprocess 执行
git worktree 隔离 — full-access 模式自动创建独立 worktree，并行任务互不干扰
阻塞 + 异步双模式 — codex 同步等待结果，codex_dispatch 立即返回后台运行
多轮对话 (resume) — 通过 session_id 延续上一次 Codex 会话
文件系统持久化 — 任务元数据存储在 ~/.codexmcp/tasks/，服务重启后可恢复
工作区日志 — 自动在 <cwd>/.codex-tasks/ 创建 symlink，IDE 中直接查看日志

工具

工具	作用	适合场景
`codex`	阻塞执行，等待完成后返回结果	代码审阅、短任务、并行模块实现
`codex_dispatch`	后台分派，立即返回 task_id	长任务（数十分钟到数小时）
`codex_status`	查询任务状态和进度	追踪后台任务、获取结果
`codex_cancel`	取消运行中的任务	终止不需要的任务

前置要求

Python 3.12+
codex CLI 已安装且在 PATH 中
tmux 已安装（full-access 模式必须）
git 已安装（full-access 模式必须）

codex --version
tmux -V
git --version

安装

从 PyPI 安装：

pip install codex-mcp-server

Claude Code

claude mcp add codex -s user --transport stdio -- \
  uvx codex-mcp-server

验证：

claude mcp list

Cursor / 通用 MCP 客户端

在 MCP 配置文件（如 mcp.json）中添加：

{
  "mcpServers": {
    "codex": {
      "command": "uvx",
      "args": ["codex-mcp-server"]
    }
  }
}

更新到最新版

uvx 会缓存已安装的包。更新到新版本时需要加 --refresh 刷新缓存：

uvx --refresh codex-mcp-server --help

注意：如果使用 PyPI 镜像源（如清华源），新版本可能需要 5-15 分钟才能同步。若 --refresh 仍拉取到旧版本，可临时指定官方源：
uvx --refresh --index-url https://pypi.org/simple/ codex-mcp-server --help

从源码安装（开发用）

git clone https://github.com/shilong20/codexmcp.git
cd codexmcp
pip install -e .

快速上手

1. 代码审阅（阻塞，只读）

{
  "tool": "codex",
  "arguments": {
    "prompt": "审阅 src/auth/ 目录的代码质量和安全性",
    "cwd": "/workspace/my-project",
    "topic": "review-auth_module-v1",
    "sandbox": "read-only"
  }
}

2. 并行模块实现（阻塞，写入）

并发调用多个 codex，每个使用不同 topic：

{
  "tool": "codex",
  "arguments": {
    "prompt": "实现用户注册模块...",
    "cwd": "/workspace/my-project",
    "topic": "implement-user_register-v1",
    "sandbox": "full-access"
  }
}

每个 full-access 任务自动创建独立的 git worktree 和分支 agent/<topic>。

3. 长任务后台分派

{
  "tool": "codex_dispatch",
  "arguments": {
    "prompt": "重构整个项目为异步架构...",
    "cwd": "/workspace/my-project",
    "topic": "longrun-async_refactor-v1",
    "sandbox": "full-access"
  }
}

立即返回 task_id。之后用 codex_status 查看进度。

4. Resume 多轮对话

首次执行返回 session_id。修改代码后继续：

{
  "tool": "codex",
  "arguments": {
    "prompt": "我已修改了代码，请重新审阅",
    "cwd": "/workspace/my-project",
    "topic": "review-auth_module-v2",
    "sandbox": "read-only",
    "session_id": "019d0aa8-..."
  }
}

resume 时 topic 版本号 +1（如 v1→v2），传入上次的 session_id。worktree 基于 <type>-<description> 生成（不含版本号），自动复用。

参数说明

参数	类型	必填	说明
`prompt`	str	是	任务指令
`cwd`	Path	是	工作目录（绝对路径）
`topic`	str	是	任务标识，格式 `<type>-<desc>-v<ver>`。用于 task_id、worktree 分支名、tmux session 名（full-access）
`sandbox`	`read-only` / `full-access`	是	权限模式。read-only 不建 worktree 不走 tmux；full-access 创建 worktree + tmux 隔离
`session_id`	str	否	恢复之前的 Codex 会话（多轮对话）

返回结构

阻塞 codex 完成后返回：

{
  "success": true,
  "task_id": "codex-implement-user_register-v1",
  "session_id": "019d0aa8-...",
  "result": "Codex 的最终回复文本",
  "exit_code": 0,
  "elapsed_seconds": 45.2,
  "usage": {"input_tokens": 5000, "output_tokens": 1200},
  "worktree_dir": "/workspace/project-agent-implement-user_register",
  "agent_branch": "agent/implement-user_register",
  "base_branch": "main",
  "diff_stat": "3 files changed, 42 insertions(+), 10 deletions(-)",
  "commits_ahead": 2
}

session_id 用于 resume
worktree 相关字段仅 full-access 模式返回
当 CODEXMCP_READONLY_FALLBACK 启用且 sandbox 为 read-only 时，返回额外的 readonly_audit 字段：

{
  "readonly_audit": {
    "mode": "fallback",
    "violations_detected": 0,
    "violations": [],
    "verdict": "CLEAN"
  }
}

verdict 为 VIOLATION 时表示检测到违规操作，violations 列出具体违规项。

环境变量

通过 MCP 服务进程环境变量配置：

变量	说明	示例
`CODEX_PROFILE`	codex 配置文件名	`fast`
`CODEX_REASONING_EFFORT`	推理强度	`high`、`xhigh`
`CODEXMCP_READONLY_FALLBACK`	容器环境下启用 read-only 降级模式（见下方说明）	`1`

Read-Only 降级模式

在 Docker 等容器环境中，read-only sandbox 可能因 bwrap namespace 限制无法正常工作。设置 CODEXMCP_READONLY_FALLBACK=1 后：

read-only 请求内部使用 danger-full-access 执行
自动注入强约束提示词，禁止任何文件修改操作
任务完成后自动审计日志，检测违规操作
返回结果中附加 readonly_audit 字段

执行路径不变：不创建 tmux session 和 git worktree，仍走 subprocess 直接执行。

日志

位置	路径
工作区 symlink	`<cwd>/.codex-tasks/<topic>/codex-exec.log`
主存储	`~/.codexmcp/tasks/<task_id>/codex-exec.log`
实时查看	`tmux attach -t codex-<topic>`（仅 full-access）

开发

git clone https://github.com/shilong20/codexmcp.git
cd codexmcp
pip install -e .

许可证

MIT License

codex-mcp-server

codex-mcp-server

特性

工具

前置要求

安装

Claude Code

Cursor / 通用 MCP 客户端

更新到最新版

从源码安装（开发用）

快速上手

1. 代码审阅（阻塞，只读）

2. 并行模块实现（阻塞，写入）

3. 长任务后台分派

4. Resume 多轮对话

参数说明

返回结构

环境变量

Read-Only 降级模式

日志

开发

许可证

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API