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

by shilong20

Overview Schema Related Servers Score Discussions

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: mcp-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

Install Server

license - permissive license

quality

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

Appeared in Searches

A server for finding information about Codex

Latest Blog Posts

Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly
Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
OpenAI
open source

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/shilong20/codexmcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server