mcp-codex-dev

<p align="center">English | <a href="README.zh-CN.md">中文</a></p>

MCP Server for integrating Codex CLI into Claude Code workflows with session management and real-time progress monitoring.

<img width="1890" height="948" alt="image" src="https://github.com/user-attachments/assets/490a8cf6-1267-42cd-8f6f-e0a82c0dc6a3" />

Installation

Prerequisites: Codex CLI installed and configured.

In .mcp.json file

{
  "mcpServers": {
    "mcp-codex-dev": {
      "command": "npx",
      "args": ["-y", "mcp-codex-dev"]
    }
  }
}

or

claude mcp add mcp-codex-dev -- npx -y mcp-codex-dev 

Windows OS:

{
  "mcpServers": {
    "mcp-codex-dev": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "mcp-codex-dev"]
    }
  }
}

or

claude mcp add mcp-codex-dev -- cmd /c npx -y mcp-codex-dev

Tools

Configuration

Create ~/.mcp/mcp-codex-dev/config.json:

{
  "model": "gpt-5.2",
  "sandbox": "danger-full-access",
  "timeout": 300000,
  "tools": {
    "tdd": { "model": "gpt-5.3-codex", "sandbox": "danger-full-access", "timeout": 2000000},
    "review": { "model": "gpt-5.2", "sandbox": "danger-full-access", "timeout": 3000000},
    "health": { "enabled": false }
  }
}

Top-level model / sandbox / timeout are global defaults. The tools section overrides per tool (keyed by tool name). Set "enabled": false to disable a tool.

Per-project config can be placed at <project>/.mcp/mcp-codex-dev.config.json.

Progress Server

A local HTTP server starts at http://localhost:23120 showing real-time progress. Configurable via progressPort.

When multiple MCP server instances run simultaneously, they share a single progress page: the first instance binds the port and serves the UI, and other instances forward their progress events to it.

Session Tracking

Session tracking metadata is stored per project at <project>/.mcp/mcp-codex-dev/sessions.json (where <project> is the Git repo root if applicable).

Codex CLI's own session files remain in ~/.codex/sessions/<id>/.

License

No license.