Content
# codex-mcp
<div align="center">
**Expose Codex CLI to AI coding assistants like Claude Code, Windsurf, and Cursor via MCP protocol**
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io)
</div>
---
## I. Project Introduction
`codex-mcp` is a **thin and stable** MCP server that packages [Codex CLI](https://developers.openai.com/codex/quickstart) into a `codex` tool callable by any MCP client. It does one thing: reliably forwards `codex exec` / `codex exec resume` calls and returns structured results to the upstream.
Key Features:
- **Asynchronous First**: All subprocess I/O uses `asyncio`, which does not block the host MCP server's event loop.
- **Dual Timeouts**: `idle_timeout` (between two lines of stdout) + `overall_timeout` (single call overall), both configurable via environment variables.
- **Windows Native Stability**: Use process groups to start codex, clean up with `CTRL_BREAK_EVENT → taskkill /F /T`, leaving no `codex.exe` / `node.exe` zombies.
- **Session Continuation**: Returned `SESSION_ID` can be used directly in subsequent calls to resume context.
- **Pure MCP Protocol**: All logs go to stderr, `stdout` is only for JSON-RPC frames.
- **Zero Prompt Escapes**: argv is passed through as a list, no longer stepping into Windows double-escape pitfalls.
---
## II. Quick Start
### 0. Prerequisites
- Python **3.12+**
- [`uv`](https://docs.astral.sh/uv/) package manager (recommended 0.5+)
- `codex` CLI **0.122+**, executable in `PATH`
- One of the target MCP clients: **Claude Code** / **Windsurf** / **Cursor**
Install `uv`:
- Windows (PowerShell)
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
- Linux / macOS
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
### 1. Installation Steps
Two methods are provided, choose one.
#### 1.1 `uvx` One-Liner (Recommended)
**No cloning needed**, `uvx` will automatically pull, build, and run from GitHub in an isolated environment:
```bash
uvx --from git+https://github.com/viklee666/codex-mcp.git codex-mcp
```
The process will wait on stdin for MCP protocol frames — normal server behavior. Press `Ctrl+C` to exit. The first execution will download and build (~10 seconds), subsequent runs use `uv` local caching.
**Fixed Version (Recommended for Production)**: add a tag to the URL:
```bash
uvx --from git+https://github.com/viklee666/codex-mcp.git@v0.1.2 codex-mcp
```
#### 1.2 Local Clone (Development / Offline Scenarios)
Suitable for users who need to modify source code, use offline, or want instant startup. Clone and sync dependencies:
```bash
git clone https://github.com/viklee666/codex-mcp.git
cd codex-mcp
uv sync --extra dev
```
After `uv sync`, the project `.venv` directory has a runnable `codex-mcp` entry:
- **Linux / macOS**: `./.venv/bin/codex-mcp`
- **Windows**: `.\.venv\Scripts\codex-mcp.exe`
Two access methods, **A recommended** (only in project directory, cross-platform, does not pollute the global environment).
**A. Use only in project directory (Recommended)**
Do not run `uv tool install`, keep it in `.venv`. Let the host AI or terminal find it in two ways:
- **A.1 MCP client directly fills in the absolute path**. Each `<details>` block in the next section provides local installation examples — change `command` to your absolute path:
- Linux / macOS: `/abs/path/to/codex-mcp/.venv/bin/codex-mcp`
- Windows: `D:\path\to\codex-mcp\.venv\Scripts\codex-mcp.exe`
- **A.2 Add `.venv` bin directory to `PATH`**, so the terminal can directly use `codex-mcp`.
Linux / macOS (write to `~/.bashrc` / `~/.zshrc`, then `source`):
```bash
export PATH="$HOME/path/to/codex-mcp/.venv/bin:$PATH"
```
Windows PowerShell (current session):
```powershell
$env:PATH = "D:\path\to\codex-mcp\.venv\Scripts;$env:PATH"
```
Permanent addition: **System Settings → Environment Variables → Path → New**, add `D:\path\to\codex-mcp\.venv\Scripts`, then reopen terminal.
**B. Install to user-level global bin (`uv tool install`)**
If you want to directly use `codex-mcp` in any directory (at the cost of installing an extra copy in the `uv` user directory):
```bash
uv tool install --editable . --force
```
`uv` default installation to:
- **Linux / macOS**: `$HOME/.local/bin/codex-mcp`
- **Windows**: `%USERPROFILE%\.local\bin\codex-mcp.exe`
**⚠️ If this directory is not in your `PATH`**, you need to add it manually:
- Linux / macOS (write to `~/.bashrc` / `~/.zshrc`):
```bash
export PATH="$HOME/.local/bin:$PATH"
```
- Windows PowerShell (permanent, write to user-level `Path`):
```powershell
[Environment]::SetEnvironmentVariable(
"Path",
[Environment]::GetEnvironmentVariable("Path", "User") + ";$env:USERPROFILE\.local\bin",
"User"
)
```
Or go to **System Settings → Environment Variables → Path → New** and add manually. A new terminal is required for it to take effect.
**Verification**
```bash
# Linux / macOS
command -v codex-mcp
# Expected (A.2): /abs/path/to/codex-mcp/.venv/bin/codex-mcp
# Expected (B): /home/<you>/.local/bin/codex-mcp
```
```powershell
# Windows
Get-Command codex-mcp | Select-Object Name, Source
```
If not found, it means the above `PATH` was not added correctly — check A.2 or B's `PATH` settings and reopen terminal.
### 2. Configure MCP Client
Choose one of three clients (or all). Each client provides **`uvx` path (default recommended)** and **local installation path (expand to view)** configurations. All runtime configurations are injected through **environment variables** (see "III. Environment Variables").
#### 2.1 Claude Code
If the old `codex` MCP server is installed, remove it first:
```bash
claude mcp remove codex
```
Add (with `uvx` path):
```bash
claude mcp add codex -s user --transport stdio -- uvx --from git+https://github.com/viklee666/codex-mcp.git codex-mcp
```
<details>
<summary>If you chose local installation (method 1.2)</summary>
If you have added the entry to `PATH` as in 1.2.A.2 or 1.2.B:
```bash
claude mcp add codex -s user --transport stdio -- codex-mcp
```
If keeping it only in project `.venv` (1.2.A.1), change to absolute path:
```bash
# Linux / macOS
claude mcp add codex -s user --transport stdio -- /abs/path/to/codex-mcp/.venv/bin/codex-mcp
# Windows
claude mcp add codex -s user --transport stdio -- "D:\path\to\codex-mcp\.venv\Scripts\codex-mcp.exe"
```
</details>
Verification:
```bash
claude mcp list
# codex: ... - ✓ Connected
```
**(Optional)** By default, allow Claude Code to automatically interact with codex: add `"mcp__codex__codex"` to the `permissions.allow` array in `~/.claude/settings.json`.
#### 2.2 Windsurf
Edit `%USERPROFILE%\.codeium\windsurf\mcp_config.json` (with `uvx` path):
```json
{
"mcpServers": {
"codex": {
"type": "stdio",
"command": "uvx",
"args": [
"--from",
"git+https://github.com/viklee666/codex-mcp.git",
"codex-mcp"
]
}
}
}
```
<details>
<summary>If you chose local installation (method 1.2)</summary>
Replace `command` with the absolute path to the `codex-mcp` executable:
- **Project `.venv` (1.2.A.1)**
- Linux / macOS: `/abs/path/to/codex-mcp/.venv/bin/codex-mcp`
- Windows: `D:\\path\\to\\codex-mcp\\.venv\\Scripts\\codex-mcp.exe` (double backslashes in JSON)
- **`uv tool install` global bin (1.2.B)**
- Linux / macOS: `$HOME/.local/bin/codex-mcp`
- Windows: `C:\\Users\\<you>\\.local\\bin\\codex-mcp.exe`
If you have added the entry to `PATH` as in 1.2.A.2 or 1.2.B, `command` can be written directly as `"codex-mcp"`.
```json
{
"mcpServers": {
"codex": {
"type": "stdio",
"command": "D:\\path\\to\\codex-mcp\\.venv\\Scripts\\codex-mcp.exe",
"args": []
}
}
}
```
</details>
Then, on Windsurf's MCP panel, disable and re-enable `codex` (or restart Windsurf) to let the client respawn a new process.
##### ⚠️ Solution for Windsurf Swallowing stderr
Windsurf's current MCP client implementation **does not retain stderr of server subprocesses** —
`codex-mcp` runtime logs (including `codex[stderr]:` recorded codex real error output)
are not visible by default. Solution: **mirror logs to a local file with `CDXMCP_LOG_FILE`**.
Add an `env` field to the `codex` node in `mcp_config.json`:
```json
{
"mcpServers": {
"codex": {
"type": "stdio",
"command": "uvx",
"args": [
"--from",
"git+https://github.com/viklee666/codex-mcp.git",
"codex-mcp"
],
"env": {
"CDXMCP_LOG_LEVEL": "INFO",
"CDXMCP_LOG_FILE": "C:\\Users\\<you>\\codex-mcp-windsurf.log"
}
}
}
}
```
To view codex subprocess stderr (model API errors, authentication failures, network disconnections, etc.),
add `"CDXMCP_DEBUG": "1"`. After disable → enable, new call logs will appear immediately in this file.
This approach is also effective in Claude Code / Cursor (they also support stderr exposure, but
`CDXMCP_LOG_FILE` unifies to a single file for centralized troubleshooting). **Note that each client uses an independent file name**
to avoid write conflicts when multiple clients write to the same file.
#### 2.3 Cursor
Edit `~/.cursor/mcp.json` (on Windows: `%USERPROFILE%\.cursor\mcp.json`, with `uvx` path):
```json
{
"mcpServers": {
"codex": {
"type": "stdio",
"command": "uvx",
"args": [
"--from",
"git+https://github.com/viklee666/codex-mcp.git",
"codex-mcp"
]
}
}
}
```
<details>
<summary>If you chose local installation (method 1.2)</summary>
Replace `command` with:
- Name `"codex-mcp"` (if you have added the entry to `PATH` as in 1.2.A.2 or 1.2.B)
- Or absolute path ( **Cursor requires this if it cannot find `codex-mcp`** ):
- Linux / macOS: `/abs/path/to/codex-mcp/.venv/bin/codex-mcp`
- Windows: `D:\\path\\to\\codex-mcp\\.venv\\Scripts\\codex-mcp.exe` (double backslashes in JSON)
```json
{
"mcpServers": {
"codex": {
"type": "stdio",
"command": "D:\\path\\to\\codex-mcp\\.venv\\Scripts\\codex-mcp.exe",
"args": []
}
}
}
```
</details>
Reload configuration in Cursor Settings → MCP panel.
### 3. Configure AI Coding Assistant Prompts (Highly Recommended)
To let the host AI (Claude Code / Cascade / Cursor) **understand** how to collaborate with codex,
add the following two prompts to your global rules file:
- Claude Code: `~/.claude/CLAUDE.md`
- Windsurf: User / Workspace Rules
- Cursor: `.md` rule files under `~/.cursor/rules/`
<details>
<summary>Expand to view complete prompts</summary>
````
## Core Instruction for CodeX MCP
At any moment, you must think about how the current process can collaborate with codex and
invoke the Codex MCP tool provided as a guarantee for your objective and comprehensive analysis.
You **must execute** the following steps:
**1** After you form a preliminary analysis of the user's needs, inform codex of the user needs and
initial ideas, and ask it to improve the needs analysis and implementation plan.
**2** Before implementing specific coding tasks, **you must ask codex for a code implementation prototype
(require codex to provide only a unified diff patch, and strictly not modify any real code)**.
After obtaining the code prototype, you **can only use this as a logical reference and rewrite it again**,
forming a production-level, highly readable, and maintainable code, and then implement specific programming modifications.
**3** Regardless of when you complete actual coding behavior, **you must immediately use codex to review
code changes and the degree of completion of the corresponding requirements**.
**4** codex can only provide references, and you **must have your own thinking, and even need to question
codex's answers**. Trusting books is not as good as not having books; your ultimate mission with codex
is to achieve a unified, comprehensive, and accurate opinion, so you must debate continuously to
find the only path to truth.
## Codex Tool Invocation Specification
### 1. Tool Overview
The codex MCP provides a tool `codex` for executing AI-assisted coding tasks. The tool **is invoked through
the MCP protocol**, without using the command line.
````
</details>
### 2. Tool Parameters
**Required** parameters:
- `PROMPT` (str): Task instruction sent to codex
- `cd` (Path): Root path of the working directory where codex executes the task
**Optional** parameters:
- `sandbox` (str): Sandbox policy, optional values:
- `"read-only"` (default): Read-only mode, safest
- `"workspace-write"`: Allow writing in the workspace
- `"danger-full-access"`: Full access permission
- `SESSION_ID` (str): Used to continue a previous session for multi-turn interaction with codex, default is `""` (empty string to start a new session)
- `skip_git_repo_check` (bool): Whether to allow running in non-Git repositories, default `True`
- `return_all_messages` (bool): Whether to return all parsed JSON events (including reasoning, tool calls, etc.), default `False`
- `image` (List[Path] | None): Attach one or more image files to the initial prompt, each path is sent independently as a `--image`, default `None`
- `model` (str): Specify the model to use, default `""` (use user's default configuration)
- `yolo` (bool): Run all commands without approval (mapped to `--dangerously-bypass-approvals-and-sandbox`), default `False`
- `profile` (str): Configuration file name loaded from `~/.codex/config.toml`, default `""` (use user's default configuration)
### 3. Return Values
On success:
```json
{
"success": true,
"SESSION_ID": "uuid-string",
"agent_messages": "agent reply text content",
"all_messages": []
}
```
(`all_messages` only appears when `return_all_messages=True`.)
On failure:
```json
{
"success": false,
"error": "error message",
"SESSION_ID": "if codex has generated thread_id, it is included, can be used to resume and retry"
}
```
### 4. Usage
Start a new conversation:
- Do not pass `SESSION_ID` (or pass an empty string `""`)
- The new `SESSION_ID` returned by the tool can be used for subsequent conversations
Continue a previous conversation:
- Pass the previously returned `SESSION_ID` as a parameter
- The context of the same session will be preserved (sandbox, working directory, profile inherited from the original session)
### 5. Invocation Specifications
**Must comply**:
- Save the returned `SESSION_ID` every time `codex` tool is called, to continue the conversation later
- `cd` parameter must point to an existing directory
- It is strictly prohibited to modify codex code; use `sandbox="read-only"` to avoid accidents, and require codex to only provide unified diff patches
Recommended usage:
- If you need to track codex's reasoning process and tool calls in detail, set `return_all_messages=True`
- For tasks such as precise positioning, debugging, and rapid code prototyping, prioritize using the codex tool
### 6. Precautions
- **Simple tasks do not require codex collaboration**
- For the same ongoing task, if there are no irresistible errors, the same `SESSION_ID` must be used
- Session management: Always track `SESSION_ID` to avoid session confusion
- Working directory: Ensure `cd` parameter points to the correct and existing directory
- Error handling: Check the `success` field of the return value and handle possible errors
- If occasional `transport closed` occurs: Mostly due to network fluctuations, retry with the original content, **do not** abuse `return_all_messages` to bypass errors
## III. Environment Variables
All configurations are injected through environment variables, no need to restart:
| Variable | Default | Effect |
| --------------------------------- | ----------- | --------------------------------------------------------------------------------------------------- |
| `CDXMCP_IDLE_TIMEOUT` | `180` | Maximum idle seconds between two stdout lines (codex may take dozens of seconds to generate long replies) |
| `CDXMCP_OVERALL_TIMEOUT` | `600` | Overall time limit for a single tool call, non-positive values indicate no limit |
| `CDXMCP_LOG_LEVEL` | `WARNING` | `DEBUG` / `INFO` / `WARNING` / `ERROR` |
| `CDXMCP_DEBUG` | Not set | Any truthy value (`1` / `true` / `yes` / `on`) forces `DEBUG` |
| `CDXMCP_LOG_FILE` | Not set | Absolute path of additional log file; if set, stderr log is **synchronously mirrored** to this file (see Windsurf chapter) |
| `CDXMCP_LOG_FILE_MAX_BYTES` | `5242880` | Single file rotation threshold (bytes) for `CDXMCP_LOG_FILE`; must be a positive decimal integer, invalid values use default and print WARNING |
| `CDXMCP_LOG_FILE_BACKUP_COUNT` | `3` | Rotation retention count for `CDXMCP_LOG_FILE`; parsing rules same as above |
| `CDXMCP_LOG_AGENT_PREVIEW_CHARS` | `1000` | Preview of `agent_messages` in INFO level log after each call; set to `0` to completely close preview (still retain single line turn summary) |
| `CDXMCP_LOG_EVENT_PAYLOADS` | Not set | Any truthy value (`1` / `true` / `yes` / `on`) records codex stdout JSON events in DEBUG level **verbatim** to log, convenient for reproducing issues like "codex returned but MCP didn't" |
| `CDXMCP_LOG_EVENT_PAYLOAD_MAX_BYTES` | `4096` | Truncation upper limit (bytes) for single event in above opt-in log; exceeds will be truncated and appended with `[truncated; full length=...]` marker. Default 4 KiB is enough to hold most `agent_message` / `turn.completed` events |
**`turn summary` line automatically recorded**: After each `codex` call, a line is output at INFO level
Compressed summary, fields separated by `|`, easy for `grep`:
```text
2026-04-24T09:30:00+0800 INFO codex_mcp.server: turn summary | success=True | thread_id=019dbcdf-... | agent_chars=1234 | events=[thread.started,turn.started,item.completed,turn.completed] | error=''
2026-04-24T09:30:00+0800 INFO codex_mcp.server: agent_messages preview: **R1 ...**\n\nEvidence:...
```
To see complete event flow content in logs, add `"CDXMCP_LOG_EVENT_PAYLOADS": "1"` in MCP config
(also need to keep `CDXMCP_DEBUG=1` or `CDXMCP_LOG_LEVEL=DEBUG`, because
detailed events are at DEBUG level).
**Privacy hint**: `DEBUG` level writes complete argv (including `PROMPT`) to stderr
and log files specified by `CDXMCP_LOG_FILE`; `agent_messages preview` and
`CDXMCP_LOG_EVENT_PAYLOADS=1` also write codex replies to files. Normal operation
keeps default `WARNING`, only open `DEBUG` when debugging locally and properly keep
`CDXMCP_LOG_FILE` permissions. To completely close agent preview, set
`CDXMCP_LOG_AGENT_PREVIEW_CHARS=0`.
**Concurrency limit**: Multiple clients / multiple workspaces on the same machine share the same `CDXMCP_LOG_FILE`
path **not guaranteed to be safe** - Python's `RotatingFileHandler` is thread-safe but not multi-process safe,
concurrent rotation on Windows may lose records due to file occupation failure. It is recommended to use independent paths for each client / workspace (e.g., `C:\...\codex-mcp-windsurf.log`, `C:\...\codex-mcp-cursor.log`).
## IV. Tool Description
<details>
<summary>Click to view codex tool parameter description</summary>
| Parameter | Type | Required | Default value | Description |
| ------------------ | ---------------------------------------------------------------- | -------- | ------------- | --------------------------------------------------------------------------- |
| `PROMPT` | `str` | √ | — | Task instruction sent to Codex |
| `cd` | `Path` | √ | — | Working directory for new sessions; ignored when resuming |
| `sandbox` | `"read-only" \| "workspace-write" \| "danger-full-access"` | × | `"read-only"` | Sandbox policy; inherited from original session when resuming |
| `SESSION_ID` | `str` | × | `""` | Empty string starts a new session; non-empty resumes corresponding Codex thread |
| `skip_git_repo_check` | `bool` | × | `True` | Append `--skip-git-repo-check` |
| `return_all_messages` | `bool` | × | `False` | Whether to return complete parsed event list |
| `image` | `List[Path] \| None` | × | `None` | Each item sent independently as a `--image` |
| `model` | `str` | × | `""` | Mapped to `--model` when non-empty |
| `yolo` | `bool` | × | `False` | Mapped to `--dangerously-bypass-approvals-and-sandbox` |
| `profile` | `str` | × | `""` | Mapped to `--profile` when non-empty; ignored when resuming |
</details>
<details>
<summary>Click to view codex tool return value structure</summary>
**On success:**
```json
{
"success": true,
"SESSION_ID": "550e8400-e29b-41d4-a716-446655440000",
"agent_messages": "Codex reply content...",
"all_messages": []
}
```
**On failure:**
```json
{
"success": false,
"error": "Error message description",
"SESSION_ID": "if codex has generated thread_id, it is included"
}
```
`all_messages` only appears when `return_all_messages=True`.
</details>
## V. FAQ
<details>
<summary>Q1: Do I need to pay extra?</summary>
`codex-mcp` itself is completely open-source and free. What really consumes tokens is your Codex CLI account.
</details>
<details>
<summary>Q2: Will parallel calls conflict?</summary>
No. Each `codex` tool call starts an independent subprocess, `SESSION_ID` isolated from each other.
If you need two calls to share context, pass the same `SESSION_ID`.
</details>
<details>
<summary>Q3: How to troubleshoot codex-mcp issues?</summary>
Temporarily set `CDXMCP_DEBUG=1` and restart the client (or disable and re-enable the corresponding MCP server),
stderr will produce detailed logs. Note that debug logs contain complete argv (including prompt), **do not send logs to public channels**.
</details>
<details>
<summary>Q4: Can I directly use Ctrl+C while codex-mcp is running?</summary>
Yes. After receiving stdin EOF or client disconnection, `codex-mcp` will exit gracefully within ~1 second,
and the corresponding `codex.exe` / `node.exe` subprocess will also be recycled with the process group.
</details>
## VI. Development
```powershell
git clone https://github.com/viklee666/codex-mcp.git
cd codex-mcp
uv sync --extra dev
uv run pytest -v
```
The test suite simulates 9 types of Codex behaviors through `tests/fake_codex.py`: normal path, multi-segment
`agent_message`, stuck (idle / overall timeout), reconnection log, non-JSON noise, non-zero exit,
missing `turn.completed`, stderr interference, error envelope of `item.completed`.
## VII. Contribution
Feel free to submit bug reports and improvement suggestions through [GitHub Issues](https://github.com/viklee666/codex-mcp/issues)
or Pull Request. Before submission, please run `uv run pytest` to ensure tests pass.
## 8. Acknowledgements
The following design elements of this project were inspired by community pioneers
[`GuDaStudio/codexmcp`](https://github.com/GuDaStudio/codexmcp`), for which we extend special thanks:
- **MCP Tool Signature**: Parameters such as `PROMPT` / `cd` / `sandbox` / `SESSION_ID` /
`skip_git_repo_check` / `return_all_messages` / `image` / `model` /
`yolo` / `profile` and their naming, order, and semantics.
- **"Thin Wrapper" Positioning**: Only performs reliable `codex exec` call forwarding, intentionally not implementing additional features such as prompt rewriting,
model routing, caching, UI, etc.
- **`Core Instruction for CodeX MCP` Prompt**: Four-step collaboration rhythm (initial analysis → prototype request →
post-completion review → maintaining independent thinking and daring to question).
- **`Codex Tool Invocation Specification` Prompt**: Chapter skeleton, session management discipline, and
`sandbox="read-only"` + unified diff patch request convention.
The starting point of this project: The author was troubled by an error repeatedly output from an upstream wrapper,
which failed to locate the actual issue—neither did it tell what `codex` said nor where the call chain broke,
but merely suggested trying `return_all_messages=True`, which, however, did not solve anything:
```json
{
"error": "Failed to get `agent_messages` from the codex session. \n\n You can try to set `return_all_messages` to `True` to get the full reasoning information. Failed to get `SESSION_ID` from the codex session. \n\n"
}
```
After exhausting debugging efforts, I decided to rewrite the runtime. While retaining the original tool signature and prompt conventions,
the entire project was redesigned with the following changes:
- Asynchronous subprocess lifecycle + `idle` / `overall` dual timeouts + three-level process cleanup
(natural-exit grace → soft signal → `taskkill /F /T`).
- **Passing codex stderr tail to the `error` field upon failure**—enabling direct observation of
what `codex` said during each failure, rather than facing empty messages like "unable to get `agent_messages`".
- 14 + 7 pytest test scenarios: The former covers subprocess lifecycle (including end-to-end verification
of multi-line Unicode prompts passed via stdin), while the latter covers `CDXMCP_LOG_FILE` dual-write configuration
and fault tolerance (parameterized expansion of about 19 assertion paths).
Both projects are based on the MIT License.
---
## License
This project is open-sourced under the [MIT License](LICENSE).
