Codex Bridge

A lightweight MCP (Model Context Protocol) server that enables AI coding assistants to interact with OpenAI's Codex AI through the official CLI. Works with Claude Code, Cursor, VS Code, and other MCP-compatible clients. Designed for simplicity, reliability, and seamless integration.

✨ Features

• Direct Codex CLI Integration: Zero API costs using official Codex CLI
• Simple MCP Tools: Two core functions for basic queries and file analysis
• Stateless Operation: No sessions, caching, or complex state management
• Production Ready: Robust error handling with configurable timeouts (default: 90 seconds)
• Minimal Dependencies: Only requires mcp>=1.0.0 and Codex CLI
• Easy Deployment: Support for both uvx and traditional pip installation
• Universal MCP Compatibility: Works with any MCP-compatible AI coding assistant

🚀 Quick Start

Prerequisites

1. Install Codex CLI:

   npm install -g @openai/codex-cli
   

2. Authenticate with Codex:

   codex
   

3. Verify installation:

   codex --version
   

Installation

🎯 Recommended: PyPI Installation

# 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: 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

🌐 Multi-Client Support

Codex Bridge works with any MCP-compatible AI coding assistant - the same server supports multiple clients through different configuration methods.

Supported MCP Clients

• Claude Code ✅ (Default)
• Cursor ✅
• VS Code ✅
• Windsurf ✅
• Cline ✅
• Void ✅
• Cherry Studio ✅
• Augment ✅
• Roo Code ✅
• Zencoder ✅
• Any MCP-compatible client ✅

Configuration Examples

<details> <summary><strong>Claude Code</strong> (Default)</summary>

# Recommended installation
claude mcp add codex-bridge -s user -- uvx codex-bridge

# Development installation
claude mcp add codex-bridge-dev -s user -- python -m src

</details> <details> <summary><strong>Cursor</strong></summary>

Global Configuration (~/.cursor/mcp.json):

{
  "mcpServers": {
    "codex-bridge": {
      "command": "uvx",
      "args": ["codex-bridge"],
      "env": {}
    }
  }
}

Project-Specific (.cursor/mcp.json in your project):

{
  "mcpServers": {
    "codex-bridge": {
      "command": "uvx",
      "args": ["codex-bridge"],
      "env": {}
    }
  }
}

Go to: Settings → Cursor Settings → MCP → Add new global MCP server

</details> <details> <summary><strong>VS Code</strong></summary>

Configuration (.vscode/mcp.json in your workspace):

{
  "servers": {
    "codex-bridge": {
      "type": "stdio",
      "command": "uvx",
      "args": ["codex-bridge"]
    }
  }
}

Alternative: Through Extensions

1. Open Extensions view (Ctrl+Shift+X)
2. Search for MCP extensions
3. Add custom server with command: uvx codex-bridge

</details> <details> <summary><strong>Windsurf</strong></summary>

Add to your Windsurf MCP configuration:

{
  "mcpServers": {
    "codex-bridge": {
      "command": "uvx",
      "args": ["codex-bridge"],
      "env": {}
    }
  }
}

</details> <details> <summary><strong>Cline</strong> (VS Code Extension)</summary>

1. Open Cline and click MCP Servers in the top navigation
2. Select Installed tab → Advanced MCP Settings
3. Add to cline_mcp_settings.json:

{
  "mcpServers": {
    "codex-bridge": {
      "command": "uvx",
      "args": ["codex-bridge"],
      "env": {}
    }
  }
}

</details> <details> <summary><strong>Void</strong></summary>

Go to: Settings → MCP → Add MCP Server

{
  "mcpServers": {
    "codex-bridge": {
      "command": "uvx",
      "args": ["codex-bridge"],
      "env": {}
    }
  }
}

</details> <details> <summary><strong>Cherry Studio</strong></summary>

1. Navigate to Settings → MCP Servers → Add Server
2. Fill in the server details:
   • Name: codex-bridge
   • Type: STDIO
   • Command: uvx
   • Arguments: ["codex-bridge"]
3. Save the configuration

</details> <details> <summary><strong>Augment</strong></summary>

Using the UI:

1. Click hamburger menu → Settings → Tools
2. Click + Add MCP button
3. Enter command: uvx codex-bridge
4. Name: Codex Bridge

Manual Configuration:

"augment.advanced": { 
  "mcpServers": [ 
    { 
      "name": "codex-bridge", 
      "command": "uvx", 
      "args": ["codex-bridge"],
      "env": {}
    }
  ]
}

</details> <details> <summary><strong>Roo Code</strong></summary>

1. Go to Settings → MCP Servers → Edit Global Config
2. Add to mcp_settings.json:

{
  "mcpServers": {
    "codex-bridge": {
      "command": "uvx",
      "args": ["codex-bridge"],
      "env": {}
    }
  }
}

</details> <details> <summary><strong>Zencoder</strong></summary>

1. Go to Zencoder menu (...) → Tools → Add Custom MCP
2. Add configuration:

{
  "command": "uvx",
  "args": ["codex-bridge"],
  "env": {}
}

1. Hit the Install button

</details> <details> <summary><strong>Alternative Installation Methods</strong></summary>

For pip-based installations:

{
  "command": "codex-bridge",
  "args": [],
  "env": {}
}

For development/local testing:

{
  "command": "python",
  "args": ["-m", "src"],
  "env": {},
  "cwd": "/path/to/codex-bridge"
}

For npm-style installation (if needed):

{
  "command": "npx",
  "args": ["codex-bridge"],
  "env": {}
}

</details>

Universal Usage

Once configured with any client, use the same two tools:

1. Ask general questions: "What authentication patterns are used in this codebase?"
2. Analyze specific files: "Review these auth files for security issues"

The server implementation is identical - only the client configuration differs!

⚙️ Configuration

Timeout Configuration

By default, Codex Bridge uses a 90-second timeout for all CLI operations. For longer queries (large files, complex analysis), you can configure a custom timeout using the CODEX_TIMEOUT environment variable.

Git Repository Check

By default, Codex CLI requires being inside a Git repository or trusted directory. If you need to use Codex Bridge in directories that aren't Git repositories, you can set the CODEX_SKIP_GIT_CHECK environment variable.

⚠️ Security Warning: Only enable this flag in trusted environments where you control the directory structure.

Example configurations:

<details> <summary><strong>Claude Code</strong></summary>

# Add with custom timeout (120 seconds)
claude mcp add codex-bridge -s user --env CODEX_TIMEOUT=120 -- uvx codex-bridge

# Add with git repository check disabled (for non-git directories)
claude mcp add codex-bridge -s user --env CODEX_SKIP_GIT_CHECK=true -- uvx codex-bridge

# Add with both configurations
claude mcp add codex-bridge -s user --env CODEX_TIMEOUT=120 --env CODEX_SKIP_GIT_CHECK=true -- uvx codex-bridge

</details> <details> <summary><strong>Manual Configuration (mcp_settings.json)</strong></summary>

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

</details>

Configuration Options:

CODEX_TIMEOUT:

• Default: 90 seconds (if not configured)
• Range: Any positive integer (seconds)
• Recommended: 60-120 seconds for most queries, 120-300 for large file analysis
• Invalid values: Fall back to 90 seconds with warning

CODEX_SKIP_GIT_CHECK:

• Default: false (Git repository check enabled)
• Valid values: "true", "1", "yes" (case-insensitive) to disable the check
• Use case: Working in directories that are not Git repositories
• Security: Only use in trusted directories you control

🛠️ Available Tools

consult_codex

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

Parameters:

• query (string): The question or prompt to send to Codex
• directory (string): Working directory for the query (default: current directory)
• format (string): Output format - "text", "json", or "code" (default: "json")
• timeout (int, optional): Timeout in seconds (recommended: 60-120, default: 90)

Example:

consult_codex(
    query="Find authentication patterns in this codebase",
    directory="/path/to/project",
    format="json",  # Default format
    timeout=90      # Default timeout
)

consult_codex_with_stdin

CLI bridge with stdin content for pipeline-friendly execution.

Parameters:

• stdin_content (string): Content to pipe as stdin (file contents, diffs, logs)
• prompt (string): The prompt to process the stdin content
• directory (string): Working directory for the query
• format (string): Output format - "text", "json"

---