openai-codex-mcp

An MCP server to wrap the OpenAI Codex CLI tool for use with Claude Code.

Overview

This project provides a simple JSON-RPC server that allows Claude Code to interact with the OpenAI Codex CLI tool. This enables Claude Code to use OpenAI's models for code generation, explanation, and problem-solving when needed.

Video Demo

https://www.loom.com/share/5d9532a79ae24b309af08c1727156f9c?sid=d9277b91-bf8c-43ec-a3c6-dc69fc52e1d2

Recent Improvements

The MCP server has been enhanced to provide a more intuitive and robust interface:

1. Specialized Methods: Added dedicated methods for common coding tasks:

   • write_code: Generate code for a specific task in a specified language
   • explain_code: Get detailed explanations of how code works
   • debug_code: Find and fix bugs in problematic code

2. Model Selection: Clearly defined model options with defaults:

   • o4-mini
   • o4-preview
   • o4-pro
   • o4-latest

3. Simplified Syntax: More intuitive parameter naming and structure for easier integration

These improvements make it easier for Claude Code to use OpenAI's models for specific programming tasks without requiring complex prompt engineering.

Prerequisites

• Python 3.12+
• OpenAI Codex CLI tool (npm install -g @openai/codex)
• Valid OpenAI API key (for the Codex CLI, not for this server)

Installation and Setup

This project uses a PEP‑621 pyproject.toml. Follow these steps:

# 1. Create & activate a venv
uv venv                     # creates a .venv/ directory
source .venv/bin/activate   # on Windows: .\.venv\Scripts\activate

# 2. Install package and dependencies into the venv
uv pip install .

After installation, the codex_server entrypoint is available in your PATH.

Running the Server

Quick Start

Use the provided setup script to automatically set up the environment and start the server:

./setup_and_run.sh

This script will:

• Check for the codex CLI installation
• Set up a Python virtual environment if needed
• Install the MCP tool via the Claude CLI if available
• Start the MCP server

Manual Start

If you prefer to start the server manually:

1. Make sure the Codex CLI is installed and properly configured with your OpenAI API key
2. Start the server:

   codex_server
   

   Alternatively, use uvicorn directly: uvicorn codex_server:app

Integrating with Claude Code

Once your MCP server is running, you can register it with Claude Code using either of these methods:

Method 1: Using the Claude CLI (Recommended)

The repository includes a configuration file that can be installed directly using the Claude CLI:

# Install the MCP tool directly from the JSON config
claude mcp add /path/to/openai_codex_mcp.json

# Verify the tool was installed correctly
claude mcp list

Method 2: Manual Configuration via UI

Alternatively, you can register the tool manually:

1. In Claude Code, navigate to Settings → Tools → Manage MCP Tools.
2. Create a new tool with:
   • Name: openai_codex
   • Description: OpenAI Codex CLI integration via MCP server
   • Base URL: http://localhost:8000/
   • Protocol: JSON-RPC 2.0
   • Authentication: leave blank
3. Save the tool.

Now, Claude Code can use the OpenAI Codex CLI tool for tasks where a different perspective or approach is desired. You can invoke it by asking Claude to use the OpenAI models for a particular task.

API Usage

The MCP server provides multiple methods to interact with OpenAI's models for different coding tasks.

Method 1: General Completion

For flexible, custom prompts to OpenAI:

curl -X POST http://localhost:8000/ \
     -H 'Content-Type: application/json' \
     -d '{
       "jsonrpc": "2.0",
       "method": "codex_completion",
       "params": {
         "prompt": "Write a JavaScript function to sort an array of objects by a property value",
         "model": "o4-mini"
       },
      

... [View full README on GitHub](https://github.com/agency-ai-solutions/openai-codex-mcp#readme)