How do I use codex-mcp-server?

1. Click on "Deploy 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

by shilong20

Overview Schema Source Related Servers Discussions Admin

Python

Local

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 中直接查看日志

Related MCP server: claude-tmux

工具

工具	作用	适合场景
`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

Available Tools

4 tools

codexA

Execute a Codex task and block until completion. Use read-only sandbox for reviews/analysis, full-access for code modifications. full-access mode creates a git worktree for isolation. Returns the final result, session_id (for resume), and git diff stats.

Inputs: prompt (required), cwd (required), topic (required), sandbox (required), +1 more. Returns: result

codex_cancelA

Cancel a running Codex task by killing its tmux session.

Inputs: task_id (required). Returns: result

codex_dispatchA

Dispatch a long-running Codex task to background and return immediately. The task runs in a persistent tmux session that survives disconnects. Use codex_status to check progress and codex_cancel to stop.

Inputs: prompt (required), cwd (required), topic (required), sandbox (required), +1 more. Returns: result

codex_statusA

Check task status. Pass task_id for single task detail (with progress events if running, or result/diff if completed). Omit task_id to list all tasks.

Inputs: task_id. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4/5.0

Scored 2026-05-26 00:40 across 4 tools

Disambiguation5/5

Each tool has a distinct role: run blocking, run async, check status, cancel. No overlap or ambiguity.

Naming Consistency4/5

Three tools use the codex_ prefix (codex_dispatch, codex_status, codex_cancel), while the main tool is just 'codex'. This minor inconsistency is acceptable as the base tool is the primary action.

Tool Count5/5

4 tools are well-scoped for managing Codex tasks: execute (sync), dispatch (async), status, cancel. No unnecessary tools.

Completeness4/5

Covers core lifecycle (start, background, status, cancel). A resume functionality is hinted via session_id but not a separate tool, which is a minor gap.

Maintenance

ActivityInactive

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

SubstrateB
co.trysubstrate
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Developer Tools Knowledge & Memory
131
https://app.trysubstrate.co/mcp
mcp-server
com.niftypm
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Project Management Communication File Systems
2
https://mcp.niftypm.com/mcp
ApuchatA
io.github.opcastil11
Real-time chat for AI agents. Claude Code, Cursor, Cline and Codex join channels over MCP.
Communication Agent Orchestration
191
https://apuchat.com/mcp
Node Command
io.github.huseyincig
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
File Systems Shell Access Browser Automation
1
https://mcp.nodecommand.app/mcp

Related MCP Servers

tmux-mcp
Shell Access Command Line
trolleydodger1988
F
license
A
quality
D
maintenance
A persistent, stateful MCP server that exposes a detached tmux session to clients, enabling shell command execution, terminal buffer reading, and control signal sending via JSON-RPC over stdio.
Updated 5 months ago (2026-06-12 15:50 UTC)
3
-
claude-tmux
Coding Agents Autonomous Agents Agent Orchestration
Ilm-Alan
A
license
A
quality
D
maintenance
MCP server for orchestrating multiple Claude Code instances via tmux, enabling spawning, reading, sending, listing, and killing sessions.
Updated 2 months ago (2026-09-26 12:44 UTC)
5
32 npm
2
MIT
Claude Code Subagent MCP
Coding Agents Command Line Version Control
ltxzs
A
license
A
quality
C
maintenance
A stdio MCP server that lets Codex Desktop/CLI delegate implementation tasks to Claude Code CLI with workspace validation, Git status checks, and session resume capabilities.
Updated 4 months ago (2026-07-18 15:00 UTC)
2
4
MIT
Vibechemy
Agent Orchestration Coding Agents
DiamondAlchemy
A
license
Not graded
quality
C
maintenance
An MCP server for orchestrating a fleet of CLI coding agents in isolated git worktrees. It exposes tools for spawning workers, sending instructions, reviewing diffs, and merging changes, with full terminal visibility.
Updated 2 months ago (2026-08-30 00:03 UTC)
8 npm
4
MIT

codex-mcp-server

特性

工具

前置要求

安装

Claude Code

Cursor / 通用 MCP 客户端

更新到最新版

从源码安装（开发用）

快速上手

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

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

3. 长任务后台分派

4. Resume 多轮对话

参数说明

返回结构

环境变量

Read-Only 降级模式

日志

开发

许可证

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

tmux-mcp

claude-tmux

Claude Code Subagent MCP

Vibechemy

Appeared in Searches