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_idcodex_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 - ✓ Connected5. 接口定义该服务提供以下主要接口接口名称功能描述主要参数返回值codex_start启动后台codex任务prompt: 提示词cwd: 工作目录approval_policy: 审批策略{ job_id, status, pid }codex_poll检查任务状态和输出job_id: 任务IDtail_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 环境要求Python3.11或更高版本codex CLIv0.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-mcp6.3 使用示例# 启动任务 codex_start( promptIn app/services/prorate_calculation_service.rb line 96, change format(...) to number_to_currency(...), cwd/Users/bbgummybear/payrollservice-thailand, approval_policyfull-auto ) # → { job_id: f3a9b2, status: running, pid: 12345 } # 轮询状态 codex_poll(job_idf3a9b2) # → { status: running, output: Reading file... } # 再次轮询 codex_poll(job_idf3a9b2) # → { 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 stderrmeta.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:0000: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: errorcat ~/.codex-async/jobs//output.txt输出消息解决方法command not found: codexcodex不在PATH中 — 添加到shell配置或在config.py中设置CODEX_BINunknown flag: --dangerously-bypass-approvals-and-sandboxCodex版本 0.125.0 — 运行npm install -g openai/codex升级permission deniedcwd不存在或Claude没有访问权限8.3 任务一直运行如果任务显示status: running但永不结束# 检查进程是否还活着 ps aux | grep codex # 查看实时输出 tail -f ~/.codex-async/jobs//output.txt # 取消任务 codex_cancel(job_id)最常见原因使用approval_policysuggest会暂停等待交互式审批。请使用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.py10. 测试pytest tests/ -v11. 注意事项异步设计服务设计为异步模式避免MCP协议超时审批策略Claude自动化必须使用full-auto策略任务持久化任务状态保存在本地文件系统重启后可恢复进程管理服务器重启后会自动检测并更新僵尸进程状态资源清理定期清理旧任务以避免磁盘空间不足