Codex MCP Wrapper

This project wraps OpenAI's Codex CLI as an MCP (Model Context Protocol) server, making it accessible through the TeaBranch/open-responses-server middleware.

Requirements

• Node 22 (nvm install 22.15.1 | nvm use 22.15.1) required for Codex

Overview

The setup consists of three main components:

1. Codex CLI: OpenAI's command-line interface for interacting with Codex.
2. MCP Wrapper Server: A Node.js Express server that forwards MCP requests to Codex CLI and formats responses as MCP.
3. open-responses-server: A middleware service that provides Responses API compatibility and MCP support.

Installation

Using Docker (Recommended)

# Clone this repository
git clone https://github.com/yourusername/codex-mcp-wrapper.git
cd codex-mcp-wrapper

# Start the services
./start.sh

This will start:

• Codex MCP wrapper on port 8080
• open-responses-server on port 3000

Manual Installation

# Install dependencies
npm install

# Install Codex CLI globally
npm install -g @openai/codex

# Start the MCP server
node mcp-server.js
# Install the package in development mode
pip install -e .

Usage

You can run the MCP server using either stdio or SSE transport:

# Using stdio (default)
python -m mcp_server

# Using SSE on a specific port
python -m mcp_server --transport sse --port 8000

Tool Documentation

run_codex

Clones a repository, checks out a specific branch (optional), navigates to a specific folder (optional), and runs Codex with the given request.

Parameters

• repository (required): Git repository URL
• branch (optional): Git branch to checkout
• folder (optional): Folder within the repository to focus on
• request (required): Codex request/prompt to run

Example

{
  "repository": "https://github.com/username/repo.git",
  "branch": "main",
  "folder": "src",
  "request": "Analyze this code and suggest improvements"
}

clone_and_write_prompt

Clones a repository, reads the system prompt from .agent/system.md, parses modelId from .agent/agent.json, writes the request to a .prompt file, and invokes the Codex CLI with the extracted model.

Parameters

• repository (required): Git repository URL
• request (required): Prompt text to run through Codex
• folder (optional, default /): Subfolder within the repository to operate in

Example

{
  "repository": "https://github.com/username/repo.git",
  "folder": "src",
  "request": "Analyze this code and suggest improvements"
}

MCPS Configuration

Place a mcps.json file under the .agent/ directory to register available MCP tools. Codex will load this configuration automatically.

Example .agent/mcps.json:

{
  "mcpServers": {
    "agentic-developer-mcp": {
      "url": "..."
    }
  }
}

Development

This project uses the MCP Python SDK to implement an MCP server. The primary implementation is in mcp_server/server.py.

License

MIT