codex-async-mcp MCP 服务说明文档-育师

1. 服务概述

一句话简介：本地MCP服务器，异步封装codex CLI - 立即返回job_id而不是阻塞，避免Claude遇到MCP协议超时错误(-32001)

服务名称：codex-async-mcp
版本号：1.0.0
开发者/提供方：benzkittisak
协议类型：MCP (Model Context Protocol)

2. 核心功能

该MCP服务提供以下主要功能：

codex_start- 在后台启动codex任务，立即返回job_id
codex_poll- 检查任务状态并获取输出尾部内容
codex_list- 列出最近的作业（按时间倒序）
codex_cancel- 终止正在运行的作业

3. 使用场景

该服务适合以下使用场景：

长时间代码生成- 执行耗时的代码生成任务而不阻塞Claude
自动化代码编辑- 批量修改代码文件
避免超时错误- 防止MCP协议超时导致的任务失败
异步任务管理- 管理多个并发的代码生成任务
代码重构- 大规模代码重构操作

4. 接入方式

4.1 服务端点

该服务为本地运行的MCP服务器，通过Python启动，提供以下工具接口：

启动任务- 异步启动codex CLI任务
轮询状态- 查询任务执行状态和输出
任务列表- 查看所有任务历史
取消任务- 终止正在运行的任务

4.2 认证与权限

服务使用本地文件系统存储任务状态，需要配置工具权限：

在settings.local.json中添加权限：

{ "permissions": { "allow": [ "mcp__codex-async__codex_start", "mcp__codex-async__codex_poll", "mcp__codex-async__codex_list", "mcp__codex-async__codex_cancel" ] } }

4.3 数据格式

服务使用以下数据格式：

任务元数据：JSON格式的任务状态信息
输出日志：文本格式的stdout和stderr输出
存储位置：~/.codex-async/jobs/{job_id}/

4.4 服务器配置

全局注册（所有项目）：

claude mcp add codex-async -s user -- python -m codex_async_mcp.server

项目级注册：

cd ~/your-project claude mcp add codex-async -- python -m codex_async_mcp.server

验证连接：

claude mcp list # codex-async: python -m codex_async_mcp.server - ✓ Connected

5. 接口定义

该服务提供以下主要接口：

接口名称	功能描述	主要参数	返回值
`codex_start`	启动后台codex任务	prompt: 提示词 cwd: 工作目录 approval_policy: 审批策略	{ job_id, status, pid }
`codex_poll`	检查任务状态和输出	job_id: 任务ID tail_lines: 输出行数（可选）	{ status, output, exit_code }
`codex_list`	列出最近的作业	limit: 返回数量（可选）	作业列表
`codex_cancel`	终止运行中的作业	job_id: 任务ID	取消确认

5.1 审批策略说明

策略值	Codex标志	行为说明
`suggest`	`-s read-only`	只读沙箱，无写入操作
`auto-edit`	`--full-auto`	自动应用编辑
`full-auto`	`--dangerously-bypass-approvals-and-sandbox`	无提示，无沙箱（推荐用于Claude自动化）

注意：对于Claude自动化，始终使用full-auto—suggest模式会等待交互式输入，而在子进程中永远不会到达。

6. 快速开始

6.1 环境要求

Python：3.11或更高版本
codex CLI：v0.125.0+，需要在$PATH中
Claude Code CLI：用于MCP客户端

6.2 安装步骤

cd ~/payroll-mcp # 或任何存放此仓库的位置 pip install -e ".[dev]"

验证安装：

python -c "from codex_async_mcp.server import mcp; print(mcp.name)" # → codex-async-mcp

6.3 使用示例

# 启动任务 codex_start( prompt="In app/services/prorate_calculation_service.rb line 96, change format(...) to number_to_currency(...)", cwd="/Users/bbgummybear/payrollservice-thailand", approval_policy="full-auto" ) # → { job_id: "f3a9b2", status: "running", pid: 12345 } # 轮询状态 codex_poll(job_id="f3a9b2") # → { status: "running", output: "Reading file..." } # 再次轮询 codex_poll(job_id="f3a9b2") # → { status: "done", exit_code: 0, output: "Applied changes to prorate_calculation_service.rb" }

7. 任务状态管理

任务存储在~/.codex-async/jobs/{job_id}/目录中：

~/.codex-async/jobs/f3a9b2/ ├── meta.json # 状态、PID、时间戳、退出码 └── output.txt # codex的stdout + stderr

meta.json 结构：

{ "job_id": "f3a9b2", "status": "running | done | error | cancelled", "prompt": "...", "cwd": "/path/to/repo", "approval_policy": "full-auto", "pid": 12345, "started_at": "2026-04-29T10:00:00+00:00", "finished_at": null, "exit_code": null }

8. 故障排除

8.1 连接失败

如果claude mcp list显示codex-async: ... - ✗ Failed：

# 检查Claude使用的Python which python # 如果使用conda，使用完整路径注册 claude mcp add codex-async -s user -- /Users/bbgummybear/miniconda3/bin/python -m codex_async_mcp.server # 验证包已安装在正确环境中 /Users/bbgummybear/miniconda3/bin/python -c "import codex_async_mcp; print('ok')"

8.2 任务立即出错

如果codex_start后立即显示status: "error"：

cat ~/.codex-async/jobs//output.txt

输出消息	解决方法
`command not found: codex`	codex不在PATH中 — 添加到shell配置或在config.py中设置CODEX_BIN
`unknown flag: --dangerously-bypass-approvals-and-sandbox`	Codex版本 < 0.125.0 — 运行`npm install -g @openai/codex`升级
`permission denied`	cwd不存在或Claude没有访问权限

8.3 任务一直运行

如果任务显示status: "running"但永不结束：

# 检查进程是否还活着 ps aux | grep codex # 查看实时输出 tail -f ~/.codex-async/jobs//output.txt # 取消任务 codex_cancel(job_id="")

最常见原因：使用approval_policy="suggest"会暂停等待交互式审批。请使用"full-auto"代替。

8.4 清理旧任务

# 查看所有任务（按日期排序） ls -lt ~/.codex-async/jobs/ # 删除7天前的任务 find ~/.codex-async/jobs -maxdepth 1 -type d -mtime +7 -exec rm -rf {} +

9. 项目结构

codex-async-mcp/ ├── README.md ├── pyproject.toml ├── src/ │ └── codex_async_mcp/ │ ├── __init__.py │ ├── server.py # MCP入口点，工具定义 │ ├── job_manager.py # spawn / poll / cancel / list │ └── config.py # JOBS_DIR, CODEX_BIN, 默认值 └── tests/ └── test_job_manager.py

10. 测试

pytest tests/ -v

11. 注意事项

异步设计：服务设计为异步模式，避免MCP协议超时
审批策略：Claude自动化必须使用full-auto策略
任务持久化：任务状态保存在本地文件系统，重启后可恢复
进程管理：服务器重启后会自动检测并更新僵尸进程状态
资源清理：定期清理旧任务以避免磁盘空间不足

codex-async-mcp MCP 服务说明文档