codex-cli-mcp

Bridge OpenAI Codex CLI to any MCP client

English | 한국어

npm · GitHub · Issues

Overview

An MCP (Model Context Protocol) server that wraps OpenAI Codex CLI as tools. It enables MCP clients like Claude Desktop, Cursor, and Windsurf to run Codex CLI sessions in headless mode.

Related MCP server: mcacp

Prerequisites

1. Install Codex CLI

Install Codex CLI (docs) and make sure it is available in your PATH:

# npm
npm install -g @openai/codex

# Homebrew (macOS)
brew install --cask codex

Or download the binary from GitHub Releases.

2. Authenticate

Option A — ChatGPT Login (Recommended)

Run codex and select "Sign in with ChatGPT". Requires a Plus, Pro, Team, Edu, or Enterprise plan.

Option B — API Key

For headless / CI environments:

export OPENAI_API_KEY="your-api-key"

See the Codex Authentication docs for more details.

Tools

See Codex Models for available models.

codex

Start a new Codex CLI session.

codex-reply

Continue an existing Codex CLI session.

Setup

For Humans

Copy the prompt below and paste it into your LLM agent — it will install and configure everything automatically:

Install and configure @nayagamez/codex-cli-mcp by following: https://raw.githubusercontent.com/nayagamez/codex-cli-mcp/main/docs/guide/installation.md

Or set it up manually — see Manual Setup below.

For LLM Agents

curl -s https://raw.githubusercontent.com/nayagamez/codex-cli-mcp/main/docs/guide/installation.md

Manual Setup

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "codex-cli-mcp": {
      "command": "npx",
      "args": ["-y", "@nayagamez/codex-cli-mcp"]
    }
  }
}

Add to your MCP settings:

{
  "mcpServers": {
    "codex-cli-mcp": {
      "command": "npx",
      "args": ["-y", "@nayagamez/codex-cli-mcp"]
    }
  }
}

claude mcp add codex-cli-mcp -- npx -y @nayagamez/codex-cli-mcp

Progress Notifications

The server sends MCP progress notifications in real-time as Codex processes your request. This lets MCP clients know the server is alive and working, not hanging.

Progress messages include:

• [5s] Session started (thread: ...) — session initialized

• [12s] Command executed: npm test — a command was run

• [18s] Message: Refactoring the auth module... — agent reasoning

• [25s] Turn completed — turn finished

Idle-based Timeout

The timeout is idle-based, not absolute. The timer resets every time the server receives an event from Codex. This means long-running tasks with continuous activity will never timeout, while truly stuck processes will be killed after the configured idle period.

• Default idle timeout: 10 minutes

• Override per-call via timeout parameter, or globally via CODEX_TIMEOUT_MS

Environment Variables

How It Works

MCP Client  →  Tool Call (codex / codex-reply)
            →  Spawn `codex exec --json --full-auto` as subprocess
            →  Stream JSONL events from stdout
            →  Send progress notifications back to client
            →  Return formatted results when done

1. The MCP client sends a tool call (codex or codex-reply)

2. The server spawns Codex CLI with --json and --full-auto flags

3. The prompt is passed via stdin

4. JSONL events are streamed and parsed in real-time

5. Progress notifications are sent to the client on each event (idle timer resets)

6. Results (messages, commands, errors, token usage) are formatted as markdown and returned

License

MIT