Skip to content
Back to search

codex-bridge

SkillWorks with CodexGitHub

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/elyin--codex-bridge/badge.svg)](/listings/elyin--codex-bridge)

HTML

<a href="/listings/elyin--codex-bridge"><img src="/api/listings/elyin--codex-bridge/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md Β· README Β· 590 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Codex Bridge
  2. ![CI Status](https://github.com/eLyiN/codex-bridge/actions/workflows/ci.yml/badge.svg)
  3. ![PyPI Version](https://img.shields.io/pypi/v/codex-bridge)
  4. ![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)
  5. ![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)
  6. ![MCP Compatible](https://img.shields.io/badge/MCP-compatible-green.svg)
  7. ![Codex CLI](https://img.shields.io/badge/Codex-CLI-blue.svg)
  8. 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.
  9. ## ✨ Features
  10. - **Direct Codex CLI Integration**: Zero API costs using official Codex CLI
  11. - **Simple MCP Tools**: Two core functions for basic queries and file analysis
  12. - **Stateless Operation**: No sessions, caching, or complex state management
  13. - **Production Ready**: Robust error handling with configurable timeouts (default: 90 seconds)
  14. - **Minimal Dependencies**: Only requires `mcp>=2,<3` and Codex CLI
  15. - **Easy Deployment**: Support for both uvx and traditional pip installation
  16. - **Universal MCP Compatibility**: Works with any MCP-compatible AI coding assistant
  17. ## πŸš€ Quick Start
  18. ### Prerequisites
  19. 1. **Install Codex CLI**:
  20. ```bash
  21. npm install -g @openai/codex-cli
  22. ```
  23. 2. **Authenticate with Codex**:
  24. ```bash
  25. codex
  26. ```
  27. 3. **Verify installation**:
  28. ```bash
  29. codex --version
  30. ```
  31. ### Installation
  32. **🎯 Recommended: PyPI Installation**
  33. ```bash
  34. # Install from PyPI
  35. pip install codex-bridge
  36. # Add to Claude Code with uvx (recommended)
  37. claude mcp add codex-bridge -s user -- uvx codex-bridge
  38. ```
  39. **Alternative: From Source**
  40. ```bash
  41. # Clone the repository
  42. git clone https://github.com/shelakh/codex-bridge.git
  43. cd codex-bridge
  44. # Build and install locally
  45. uvx --from build pyproject-build
  46. pip install dist/*.whl
  47. # Add to Claude Code
  48. claude mcp add codex-bridge -s user -- uvx codex-bridge
  49. ```
  50. **Development Installation**
  51. ```bash
  52. # Clone and install in development mode
  53. git clone https://github.com/shelakh/codex-bridge.git
  54. cd codex-bridge
  55. pip install -e .
  56. # Add to Claude Code (development)
  57. claude mcp add codex-bridge-dev -s user -- python -m src
  58. ```
  59. ## 🌐 Multi-Client Support
  60. **Codex Bridge works with any MCP-compatible AI coding assistant** - the same server supports multiple clients through different configuration methods.
  61. ### Supported MCP Clients
  62. - **Claude Code** βœ… (Default)
  63. - **Cursor** βœ…
  64. - **VS Code** βœ…
  65. - **Windsurf** βœ…
  66. - **Cline** βœ…
  67. - **Void** βœ…
  68. - **Cherry Studio** βœ…
  69. - **Augment** βœ…
  70. - **Roo Code** βœ…
  71. - **Zencoder** βœ…
  72. - **Any MCP-compatible client** βœ…
  73. ### Configuration Examples
  74. <details>
  75. <summary><strong>Claude Code</strong> (Default)</summary>
  76. ```bash
  77. # Recommended installation
  78. claude mcp add codex-bridge -s user -- uvx codex-bridge
  79. # Development installation
  80. claude mcp add codex-bridge-dev -s user -- python -m src
  81. ```
  82. </details>
  83. <details>
  84. <summary><strong>Cursor</strong></summary>
  85. **Global Configuration** (`~/.cursor/mcp.json`):
  86. ```json
  87. {
  88. "mcpServers": {
  89. "codex-bridge": {
  90. "command": "uvx",
  91. "args": ["codex-bridge"],
  92. "env": {}
  93. }
  94. }
  95. }
  96. ```
  97. **Project-Specific** (`.cursor/mcp.json` in your project):
  98. ```json
  99. {
  100. "mcpServers": {
  101. "codex-bridge": {
  102. "command": "uvx",
  103. "args": ["codex-bridge"],
  104. "env": {}
  105. }
  106. }
  107. }
  108. ```
  109. Go to: `Settings` β†’ `Cursor Settings` β†’ `MCP` β†’ `Add new global MCP server`
  110. </details>
  111. <details>
  112. <summary><strong>VS Code</strong></summary>
  113. **Configuration** (`.vscode/mcp.json` in your workspace):
  114. ```json
  115. {
  116. "servers": {
  117. "codex-bridge": {
  118. "type": "stdio",
  119. "command": "uvx",
  120. "args": ["codex-bridge"]
  121. }
  122. }
  123. }
  124. ```
  125. **Alternative: Through Extensions**
  126. 1. Open Extensions view (Ctrl+Shift+X)
  127. 2. Search for MCP extensions
  128. 3. Add custom server with command: `uvx codex-bridge`
  129. </details>
  130. <details>
  131. <summary><strong>Windsurf</strong></summary>
  132. Add to your Windsurf MCP configuration:
  133. ```json
  134. {
  135. "mcpServers": {
  136. "codex-bridge": {
  137. "command": "uvx",
  138. "args": ["codex-bridge"],
  139. "env": {}
  140. }
  141. }
  142. }
  143. ```
  144. </details>
  145. <details>
  146. <summary><strong>Cline</strong> (VS Code Extension)</summary>
  147. 1. Open Cline and click **MCP Servers** in the top navigation
  148. 2. Select **Installed** tab β†’ **Advanced MCP Settings**
  149. 3. Add to `cline_mcp_settings.json`:
  150. ```json
  151. {
  152. "mcpServers": {
  153. "codex-bridge": {
  154. "command": "uvx",
  155. "args": ["codex-bridge"],
  156. "env": {}
  157. }
  158. }
  159. }
  160. ```
  161. </details>
  162. <details>
  163. <summary><strong>Void</strong></summary>
  164. Go to: `Settings` β†’ `MCP` β†’ `Add MCP Server`
  165. ```json
  166. {
  167. "mcpServers": {
  168. "codex-bridge": {
  169. "command": "uvx",
  170. "args": ["codex-bridge"],
  171. "env": {}
  172. }
  173. }
  174. }
  175. ```
  176. </details>
  177. <details>
  178. <summary><strong>Cherry Studio</strong></summary>
  179. 1. Navigate to **Settings β†’ MCP Servers β†’ Add Server**
  180. 2. Fill in the server details:
  181. - **Name**: `codex-bridge`
  182. - **Type**: `STDIO`
  183. - **Command**: `uvx`
  184. - **Arguments**: `["codex-bridge"]`
  185. 3. Save the configuration
  186. </details>
  187. <details>
  188. <summary><strong>Augment</strong></summary>
  189. **Using the UI:**
  190. 1. Click hamburger menu β†’ **Settings** β†’ **Tools**
  191. 2. Click **+ Add MCP** button
  192. 3. Enter command: `uvx codex-bridge`
  193. 4. Name: **Codex Bridge**
  194. **Manual Configuration:**
  195. ```json
  196. "augment.advanced": {
  197. "mcpServers": [
  198. {
  199. "name": "codex-bridge",
  200. "command": "uvx",
  201. "args": ["codex-bridge"],
  202. "env": {}
  203. }
  204. ]
  205. }
  206. ```
  207. </details>
  208. <details>
  209. <summary><strong>Roo Code</strong></summary>
  210. 1. Go to **Settings β†’ MCP Servers β†’ Edit Global Config**
  211. 2. Add to `mcp_settings.json`:
  212. ```json
  213. {
  214. "mcpServers": {
  215. "codex-bridge": {
  216. "command": "uvx",
  217. "args": ["codex-bridge"],
  218. "env": {}
  219. }
  220. }
  221. }
  222. ```
  223. </details>
  224. <details>
  225. <summary><strong>Zencoder</strong></summary>
  226. 1. Go to Zencoder menu (...) β†’ **Tools** β†’ **Add Custom MCP**
  227. 2. Add configuration:
  228. ```json
  229. {
  230. "command": "uvx",
  231. "args": ["codex-bridge"],
  232. "env": {}
  233. }
  234. ```
  235. 3. Hit the **Install** button
  236. </details>
  237. <details>
  238. <summary><strong>Alternative Installation Methods</strong></summary>
  239. **For pip-based installations:**
  240. ```json
  241. {
  242. "command": "codex-bridge",
  243. "args": [],
  244. "env": {}
  245. }
  246. ```
  247. **For development/local testing:**
  248. ```json
  249. {
  250. "command": "python",
  251. "args": ["-m", "src"],
  252. "env": {},
  253. "cwd": "/path/to/codex-bridge"
  254. }
  255. ```
  256. **For npm-style installation** (if needed):
  257. ```json
  258. {
  259. "command": "npx",
  260. "args": ["codex-bridge"],
  261. "env": {}
  262. }
  263. ```
  264. </details>
  265. ### Universal Usage
  266. Once configured with any client, use the same two tools:
  267. 1. **Ask general questions**: "What authentication patterns are used in this codebase?"
  268. 2. **Analyze specific files**: "Review these auth files for security issues"
  269. **The server implementation is identical** - only the client configuration differs!
  270. ## βš™οΈ Configuration
  271. ### Timeout Configuration
  272. 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.
  273. ### Git Repository Check
  274. 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.
  275. **⚠️ Security Warning**: Only enable this flag in trusted environments where you control the directory structure.
  276. **Example configurations:**
  277. <details>
  278. <summary><strong>Claude Code</strong></summary>
  279. ```bash
  280. # Add with custom timeout (120 seconds)
  281. claude mcp add codex-bridge -s user --env CODEX_TIMEOUT=120 -- uvx codex-bridge
  282. # Add with git repository check disabled (for non-git directories)
  283. claude mcp add codex-bridge -s user --env CODEX_SKIP_GIT_CHECK=true -- uvx codex-bridge
  284. # Add with both configurations
  285. claude mcp add codex-bridge -s user --env CODEX_TIMEOUT=120 --env CODEX_SKIP_GIT_CHECK=true -- uvx codex-bridge
  286. ```
  287. </details>
  288. <details>
  289. <summary><strong>Manual Configuration (mcp_settings.json)</strong></summary>
  290. ```json
  291. {
  292. "mcpServers": {
  293. "codex-bridge": {
  294. "command": "uvx",
  295. "args": ["codex-bridge"],
  296. "env": {
  297. "CODEX_TIMEOUT": "120",
  298. "CODEX_SKIP_GIT_CHECK": "true"
  299. }
  300. }
  301. }
  302. }
  303. ```
  304. </details>
  305. **Configuration Options:**
  306. **CODEX_TIMEOUT:**
  307. - **Default**: 90 seconds (if not configured)
  308. - **Range**: Any positive integer (seconds)
  309. - **Recommended**: 60-120 seconds for most queries, 120-300 for large file analysis
  310. - **Invalid values**: Fall back to 90 seconds with warning
  311. **CODEX_SKIP_GIT_CHECK:**
  312. - **Default**: false (Git repository check enabled)
  313. - **Valid values**: "true", "1", "yes" (case-insensitive) to disable the check
  314. - **Use case**: Working in directories that are not Git repositories
  315. - **Security**: Only use in trusted directories you control
  316. ## πŸ› οΈ Available Tools
  317. ### `consult_codex`
  318. Direct CLI bridge for simple queries with structured JSON output by default.
  319. **Parameters:**
  320. - `query` (string): The question or prompt to send to Codex
  321. - `directory` (string): Working directory for the query (default: current directory)
  322. - `format` (string): Output format - "text", "json", or "code" (default: "json")
  323. - `timeout` (int, optional): Timeout in seconds (recommended: 60-120, default: 90)
  324. **Example:**
  325. ```python
  326. consult_codex(
  327. query="Find authentication patterns in this codebase",
  328. directory="/path/to/project",
  329. format="json", # Default format
  330. timeout=90 # Default timeout
  331. )
  332. ```
  333. ### `consult_codex_with_stdin`
  334. CLI bridge with stdin content for pipeline-friendly execution.
  335. **Parameters:**
  336. - `stdin_content` (string): Content to pipe as stdin (file contents, diffs, logs)
  337. - `prompt` (string): The prompt to process the stdin content
  338. - `directory` (string): Working directory for the query
  339. - `format` (string): Output format - "text", "json", or "code" (default: "json")
  340. - `timeout` (int, optional): Timeout in seconds (recommended: 60-120, default: 90)
  341. ### `consult_codex_batch`
  342. Batch processing for multiple queries - perfect for CI/CD automation.
  343. **Parameters:**
  344. - `queries` (list): List of query dictionaries with 'query' and optional 'timeout'
  345. - `directory` (string): Working directory for all queries
  346. - `format` (string): Output format - currently only "json" supported for batch
  347. **Example:**
  348. ```python
  349. consult_codex_with_stdin(
  350. stdin_content=open("src/auth.py").read(),
  351. prompt="Analyze this auth file and suggest improvements",
  352. directory="/path/to/project",
  353. format="json", # Default format
  354. timeout=120 # Custom timeout for complex analysis
  355. )
  356. ```
  357. ## πŸ“‹ Usage Examples
  358. ### Basic Code Analysis
  359. ```python
  360. # Simple research query
  361. consult_codex(
  362. query="What authentication patterns are used in this project?",
  363. directory="/Users/dev/my-project"
  364. )
  365. ```
  366. ### Detailed File Review
  367. ```python
  368. # Analyze specific files
  369. with open("/Users/dev/my-project/src/auth.py") as f:
  370. auth_content = f.read()
  371. consult_codex_with_stdin(
  372. stdin_content=auth_content,
  373. prompt="Review this file and suggest security improvements",
  374. directory="/Users/dev/my-project",
  375. format="json", # Structured output
  376. timeout=120 # Allow more time for detailed analysis
  377. )
  378. ```
  379. ### Batch Processing
  380. ```python
  381. # Process multiple queries at once
  382. consult_codex_batch(
  383. queries=[
  384. {"query": "Analyze authentication patterns", "timeout": 60},
  385. {"query": "Review database implementations", "timeout": 90},
  386. {"query": "Check security vulnerabilities", "timeout": 120}
  387. ],
  388. directory="/Users/dev/my-project",
  389. format="json" # Always JSON for batch processing
  390. )
  391. ```
  392. ## πŸ—οΈ Architecture
  393. ### Core Design
  394. - **CLI-First**: Direct subprocess calls to `codex` command
  395. - **Stateless**: Each tool call is independent with no session state
  396. - **Configurable Timeout**: 90-second default execution time (configurable)
  397. - **Structured Output**: JSON format by default for better integration
  398. - **Simple Error Handling**: Clear error messages with fail-fast approach
  399. ### Project Structure
  400. ```
  401. codex-bridge/
  402. β”œβ”€β”€ src/
  403. β”‚ β”œβ”€β”€ __init__.py # Entry point
  404. β”‚ β”œβ”€β”€ __main__.py # Module execution entry point
  405. β”‚ └── mcp_server.py # Main MCP server implementation
  406. β”œβ”€β”€ .github/ # GitHub templates and workflows
  407. β”œβ”€β”€ pyproject.toml # Python package configuration
  408. β”œβ”€β”€ README.md # This file
  409. β”œβ”€β”€ CONTRIBUTING.md # Contribution guidelines
  410. β”œβ”€β”€ CODE_OF_CONDUCT.md # Community standards
  411. β”œβ”€β”€ SECURITY.md # Security policies
  412. β”œβ”€β”€ CHANGELOG.md # Version history
  413. └── LICENSE # MIT license
  414. ```
  415. ## πŸ”§ Development
  416. ### Local Testing
  417. ```bash
  418. # Install in development mode
  419. pip install -e .
  420. # Run directly
  421. python -m src
  422. # Test CLI availability
  423. codex --version
  424. ```
  425. ### Integration with Claude Code
  426. The server automatically integrates with Claude Code when properly configured through the MCP protocol.
  427. ## πŸ” Troubleshooting
  428. ### CLI Not Available
  429. ```bash
  430. # Install Codex CLI
  431. npm install -g @openai/codex-cli
  432. # Authenticate
  433. codex auth login
  434. # Test
  435. codex --version
  436. ```
  437. ### Connection Issues
  438. - Verify Codex CLI is properly authenticated
  439. - Check network connectivity
  440. - Ensure Claude Code MCP configuration is correct
  441. - Check that the `codex` command is in your PATH
  442. ### Common Error Messages
  443. - **"CLI not available"**: Codex CLI is not installed or not in PATH
  444. - **"Authentication required"**: Run `codex auth login`
  445. - **"Timeout after X seconds"**: Query took too long, try increasing timeout or breaking into smaller parts
  446. ## 🀝 Contributing
  447. We welcome contributions from the community! Please read our [Contributing Guidelines](CONTRIBUTING.md) for details on how to get started.
  448. ### Quick Contributing Guide
  449. 1. Fork the repository
  450. 2. Create a feature branch
  451. 3. Make your changes
  452. 4. Add tests if applicable
  453. 5. Submit a pull request
  454. ## πŸ“„ License
  455. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  456. ## πŸ”„ Version History
  457. See [CHANGELOG.md](CHANGELOG.md) for detailed version history.
  458. ## πŸ†˜ Support
  459. - **Issues**: Report bugs or request features via [GitHub Issues](https://github.com/shelakh/codex-bridge/issues)
  460. - **Discussions**: Join the community discussion
  461. - **Documentation**: Additional docs can be created in the `docs/` directory
  462. ---
  463. **Focus**: A simple, reliable bridge between Claude Code and Codex AI through the official CLI.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.