codex-async-mcp

codex CLIを非同期でラップするローカルMCPサーバー。ブロックせずにjob_idを即座に返すため、ClaudeがMCPプロトコルのタイムアウト（-32001）に達することはありません。

要件

Python 3.11以上
codex CLIがインストールされており、$PATHに含まれていること（v0.125.0以上）
Claude Code CLI

インストール

cd ~/payroll-mcp   # or wherever this repo lives
pip install -e ".[dev]"

確認:

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

Claudeへの登録

グローバル（すべてのプロジェクト）

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

プロジェクトのみ

cd ~/payrollservice-thailand   # or any project
claude mcp add codex-async -- python -m codex_async_mcp.server

確認

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

ツール権限の追加 (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"
    ]
  }
}

ツール

ツール	説明
`codex_start(prompt, cwd, approval_policy?)`	バックグラウンドでcodexを開始 → `job_id`を即座に返す
`codex_poll(job_id, tail_lines?)`	ステータスと出力の末尾を確認
`codex_list(limit?)`	最近のジョブを一覧表示（新しい順）
`codex_cancel(job_id)`	実行中のジョブを強制終了

approval_policyの値

値	Codexフラグ	動作
`suggest`	`-s read-only`	読み取り専用サンドボックス、書き込みなし
`auto-edit`	`--full-auto`	編集を自動適用
`full-auto`	`--dangerously-bypass-approvals-and-sandbox`	プロンプトなし、サンドボックスなし

Claudeの自動化には常にfull-autoを使用してください — suggestモードは対話的な入力を待ちますが、サブプロセス内では入力が届かないためです。

使用例

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" }

ジョブの状態

ジョブは~/.codex-async/jobs/{job_id}/に保存されます:

~/.codex-async/jobs/f3a9b2/
  meta.json     ← status, pid, timestamps, exit_code
  output.txt    ← stdout + stderr from codex

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
}

トラブルシューティング

`claude mcp list`で`codex-async: ... - ✗ Failed`と表示される

Pythonが見つからないか、パッケージが正しい環境にインストールされていません。

# Check which python Claude is using
which python

# If using conda, register with the full path
claude mcp add codex-async -s user -- /Users/bbgummybear/miniconda3/bin/python -m codex_async_mcp.server

# Verify the package is installed in that environment
/Users/bbgummybear/miniconda3/bin/python -c "import codex_async_mcp; print('ok')"

`codex_start`の直後に`status: "error"`になる

Codexの起動に失敗しました。生の出力を確認してください:

cat ~/.codex-async/jobs/<job_id>/output.txt

一般的な原因:

出力メッセージ	修正方法
`command not found: codex`	`codex`がPATHにありません — シェルプロファイルに追加するか、`config.py`で`CODEX_BIN`を設定してください
`unknown flag: --dangerously-bypass-approvals-and-sandbox`	Codexのバージョンが0.125.0未満です — `npm install -g @openai/codex`を実行してアップグレードしてください
`permission denied`	`cwd`が存在しないか、Claudeにアクセス権がありません

`status: "running"`のまま終了しない

サブプロセスがハングしています（入力を待機しているか、ループに陥っています）。

# Check if the process is still alive
ps aux | grep codex

# Check live output
tail -f ~/.codex-async/jobs/<job_id>/output.txt

# Cancel the job
codex_cancel(job_id="<job_id>")

最も一般的な原因: approval_policy="suggest"を使用しているため、対話的な承認を待機しています。代わりに"full-auto"を使用してください。

サーバー再起動後にジョブが`status: "running"`と表示される

MCPサーバーは再起動時にメモリ内のPopenレジストリを失います。次回のcodex_poll呼び出し時にPIDが終了していることが検出され、ステータスが自動的に更新されます。

codex_poll(job_id="<job_id>")
# → { status: "done", ... }   ← auto-resolved on first poll

古いジョブがディスクを圧迫している

# View all jobs sorted by date
ls -lt ~/.codex-async/jobs/

# Delete jobs older than 7 days
find ~/.codex-async/jobs -maxdepth 1 -type d -mtime +7 -exec rm -rf {} +

プロジェクト構造

codex-async-mcp/
├── README.md
├── pyproject.toml
├── src/
│   └── codex_async_mcp/
│       ├── __init__.py
│       ├── server.py        # MCP entry point, tool definitions
│       ├── job_manager.py   # spawn / poll / cancel / list
│       └── config.py        # JOBS_DIR, CODEX_BIN, defaults
└── tests/
    └── test_job_manager.py

テストの実行

pytest tests/ -v

codex-async-mcp

codex-async-mcp

要件

インストール

Claudeへの登録

グローバル（すべてのプロジェクト）

プロジェクトのみ

確認

ツール権限の追加 (settings.local.json)

ツール

approval_policyの値

使用例

ジョブの状態

トラブルシューティング

`claude mcp list`で`codex-async: ... - ✗ Failed`と表示される

`codex_start`の直後に`status: "error"`になる

`status: "running"`のまま終了しない

サーバー再起動後にジョブが`status: "running"`と表示される

古いジョブがディスクを圧迫している

プロジェクト構造

テストの実行

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API

codex-async-mcp

要件

インストール

Claudeへの登録

グローバル（すべてのプロジェクト）

プロジェクトのみ

確認

ツール権限の追加 (settings.local.json)

ツール

approval_policyの値

使用例

ジョブの状態

トラブルシューティング

claude mcp listでcodex-async: ... - ✗ Failedと表示される

codex_startの直後にstatus: "error"になる

status: "running"のまま終了しない

サーバー再起動後にジョブがstatus: "running"と表示される

古いジョブがディスクを圧迫している

プロジェクト構造

テストの実行

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API

`claude mcp list`で`codex-async: ... - ✗ Failed`と表示される

`codex_start`の直後に`status: "error"`になる

`status: "running"`のまま終了しない

サーバー再起動後にジョブが`status: "running"`と表示される