Skip to main content
Glama
deenesjakoruzh
benzkittisak

codex-async-mcp

by benzkittisak
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

codex-async-mcp

Локальный MCP-сервер, который оборачивает CLI codex асинхронно — немедленно возвращает job_id вместо блокировки, поэтому Claude никогда не достигает тайм-аута протокола MCP (-32001).

Требования

  • Python 3.11+

  • CLI codex установлен и находится в $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
}

Устранение неполадок

codex-async: ... - ✗ Failed в claude mcp list

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')"

status: "error" сразу после codex_start

Codex не удалось запустить. Проверьте необработанный вывод:

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

Распространенные причины:

Сообщение вывода

Исправление

command not found: codex

codex отсутствует в PATH — добавьте в профиль оболочки или установите CODEX_BIN в config.py

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
Install Server
F
license - not found
A
quality
C
maintenance

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

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

Tools

Latest Blog Posts

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/benzkittisak/claude-codex-mcp'

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