Codex Bridge

A lightweight MCP server bridging AI agents to OpenAI models via official CLI

python

81

GitHub Stars

python

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "elyin-codex-bridge": {
      "command": "uvx",
      "args": [
        "codex-bridge"
      ],
      "env": {
        "CODEX_TIMEOUT": "90",
        "CODEX_SKIP_GIT_CHECK": "true"
      }
    }
  }
}

Codex Bridge is a lightweight MCP server that lets you connect Claude Code, Cursor, VS Code, and other MCP-compatible clients to OpenAI's Codex via the official Codex CLI. It runs without session state, keeps dependencies minimal, and provides robust, configurable timeouts so you can perform general questions or file analyses directly from your coding environment.

How to use

You use Codex Bridge as a bridge between your MCP client and Codex CLI. The same server supports multiple clients by configuring each client to connect to Codex Bridge with its own MCP server entry. There are two core actions you’ll perform most often:

Ask general questions about code or concepts to get quick, contextual answers. 2) Analyze or review specific files by piping content through the bridge for structured feedback.

The server is stateless, so each request is independent. It uses a default 90-second timeout for Codex CLI operations, which you can adjust with environment configuration when needed.

Key workflows you’ll use include the two built-in tools that forward your prompts to Codex and return structured results. You can tailor timeouts and Git-related checks to fit your working environment.

How to install

Prerequisites you need to prepare before running Codex Bridge:

Codex CLI must be installed and available in your shell.
Python and pip should be available if you plan to install Codex Bridge from PyPI and run in Python mode.
A MCP client (such as Claude Code, Cursor, or VS Code) ready to connect to Codex Bridge.

Proceed with one of the following installation flows.

Install from PyPI (recommended)

# Install from PyPI
pip install codex-bridge

# Add to Claude Code with uvx (recommended)
claude mcp add codex-bridge -s user -- uvx codex-bridge

Alternative: Install from source

# Clone the repository
git clone https://github.com/shelakh/codex-bridge.git
cd codex-bridge

# Build and install locally
uvx --from build pyproject-build
pip install dist/*.whl

# Add to Claude Code
claude mcp add codex-bridge -s user -- uvx codex-bridge

Development installation

# Clone and install in development mode
git clone https://github.com/shelakh/codex-bridge.git
cd codex-bridge
pip install -e .

# Add to Claude Code (development)
claude mcp add codex-bridge-dev -s user -- python -m src

Available tools

consult_codex

Direct CLI bridge for simple queries with structured JSON output by default.

consult_codex_with_stdin

CLI bridge with stdin content for pipeline-friendly execution.

consult_codex_batch

Batch processing for multiple queries suitable for CI/CD automation.