mcp-codex-dev
# mcp-codex-dev
<p align="center">English | <a href="README.zh-CN.md">中文</a></p>
MCP Server for integrating [Codex CLI](https://github.com/openai/codex) 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](https://github.com/openai/codex) installed and configured.
In .mcp.json file
```
{
"mcpServers": {
"mcp-codex-dev": {
"command": "npx",
"args": ["-y", "mcp-codex-dev"]
}
}
}
```
or
```bash
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
```powershell
claude mcp add mcp-codex-dev -- cmd /c npx -y mcp-codex-dev
```
## Tools
| Tool | Description |
|------|-------------|
|`exec`|Clean dialogue without templates, supports session resume|
|`tdd`|Codex CLI with built-in test-driven development prompt template|
| `review` | Code review (spec + quality in parallel), supports resume |
| `health` | Environment and config diagnostics |
| `session_list` | List tracked sessions |
| `session_discard` | Discard sessions |
## Configuration
Create `~/.mcp/mcp-codex-dev/config.json`:
```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.
TDQS
Scored across 6 tools
Each tool has a clearly distinct purpose: exec for raw CLI execution, health for environment checks, review for code reviews, session_discard and session_list for session management, and tdd for TDD-based implementation. There is no overlap or ambiguity in functionality, making tool selection straightforward for an agent.
Most tools follow a consistent verb-based naming pattern (exec, health, review, tdd), but session_discard and session_list deviate with a noun_verb structure. This minor inconsistency is still readable and does not severely impact usability, though it breaks the overall pattern slightly.
With 6 tools, the server is well-scoped for its purpose of interacting with Codex CLI. Each tool serves a specific, necessary function (execution, health checks, reviews, session management, TDD), and none feel redundant or out of place, making the count appropriate.
The tool set covers core workflows for Codex CLI interaction, including execution, health, reviews, and session management. However, there are minor gaps, such as no explicit tool for creating or updating sessions beyond resume capabilities, which agents might need to work around using exec or other tools.