Codex Bridge

🚀 Codex Bridge

Codex Bridge 是一个轻量级的 MCP（模型上下文协议）服务器，它能让 AI 编码助手通过官方 CLI 与 OpenAI 的 Codex AI 进行交互。它可与 Claude Code、Cursor、VS Code 等支持 MCP 的客户端配合使用，具备简单、可靠和无缝集成的特点。

🚀 快速开始

前提条件

1. 安装 Codex CLI：

   npm install -g @openai/codex-cli
   

2. 使用 Codex 进行身份验证：

   codex
   

3. 验证安装：

   codex --version
   

安装

🎯 推荐：通过 PyPI 安装

# 从 PyPI 安装
pip install codex-bridge

# 使用 uvx 将其添加到 Claude Code（推荐）
claude mcp add codex-bridge -s user -- uvx codex-bridge

替代方案：从源码安装

# 克隆仓库
git clone https://github.com/shelakh/codex-bridge.git
cd codex-bridge

# 构建并在本地安装
uvx --from build pyproject-build
pip install dist/*.whl

# 添加到 Claude Code
claude mcp add codex-bridge -s user -- uvx codex-bridge

开发环境安装

# 克隆并以开发模式安装
git clone https://github.com/shelakh/codex-bridge.git
cd codex-bridge
pip install -e .

# 添加到 Claude Code（开发环境）
claude mcp add codex-bridge-dev -s user -- python -m src

✨ 主要特性

• 直接集成 Codex CLI：使用官方 Codex CLI，无需 API 成本。
• 简单的 MCP 工具：具备两个核心功能，可进行基本查询和文件分析。
• 无状态操作：无需会话、缓存或复杂的状态管理。
• 可用于生产环境：具备强大的错误处理能力，可配置超时时间（默认 90 秒）。
• 依赖极少：仅需 mcp>=1.0.0 和 Codex CLI。
• 易于部署：支持 uvx 和传统的 pip 安装方式。
• 通用 MCP 兼容性：可与任何支持 MCP 的 AI 编码助手配合使用。

🌐 多客户端支持

Codex Bridge 可与任何支持 MCP 的 AI 编码助手配合使用 —— 同一服务器可通过不同的配置方法支持多个客户端。

支持的 MCP 客户端

• Claude Code ✅（默认）
• Cursor ✅
• VS Code ✅
• Windsurf ✅
• Cline ✅
• Void ✅
• Cherry Studio ✅
• Augment ✅
• Roo Code ✅
• Zencoder ✅
• 任何支持 MCP 的客户端 ✅

配置示例

# 推荐安装方式
claude mcp add codex-bridge -s user -- uvx codex-bridge

# 开发环境安装方式
claude mcp add codex-bridge-dev -s user -- python -m src

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

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

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

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

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

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

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

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

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

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

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

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

通用用法

与任何客户端完成配置后，可使用以下两个相同的工具：

1. 提出常规问题：“此代码库中使用了哪些身份验证模式？”
2. 分析特定文件：“审查这些身份验证文件，查找安全问题”

服务器的实现方式是相同的 —— 仅客户端配置有所不同！

⚙️ 配置

超时配置

默认情况下，Codex Bridge 对所有 CLI 操作使用 90 秒的超时时间。对于较长的查询（大文件、复杂分析），可使用 CODEX_TIMEOUT 环境变量配置自定义超时时间。

Git 仓库检查

默认情况下，Codex CLI 要求在 Git 仓库或受信任的目录中使用。如果需要在非 Git 仓库的目录中使用 Codex Bridge，可设置 CODEX_SKIP_GIT_CHECK 环境变量。

⚠️ 安全警告：仅在你能控制目录结构的受信任环境中启用此标志。

示例配置：

# 添加自定义超时时间（120 秒）
claude mcp add codex-bridge -s user --env CODEX_TIMEOUT=120 -- uvx codex-bridge

# 禁用 Git 仓库检查（用于非 Git 目录）
claude mcp add codex-bridge -s user --env CODEX_SKIP_GIT_CHECK=true -- uvx codex-bridge

# 同时添加两种配置
claude mcp add codex-bridge -s user --env CODEX_TIMEOUT=120 --env CODEX_SKIP_GIT_CHECK=true -- uvx codex-bridge

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

配置选项：

CODEX_TIMEOUT：

• 默认值：90 秒（未配置时）
• 范围：任何正整数（秒）
• 推荐值：大多数查询为 60 - 120 秒，大文件分析为 120 - 300 秒
• 无效值：回退到 90 秒并给出警告

CODEX_SKIP_GIT_CHECK：

• 默认值：false（启用 Git 仓库检查）
• 有效值："true"、"1"、"yes"（不区分大小写），用于禁用检查
• 使用场景：在非 Git 仓库的目录中工作
• 安全性：仅在你能控制的受信任目录中使用

🛠️ 可用工具

consult_codex

这是一个直接的 CLI 桥接工具，默认以结构化的 JSON 格式输出简单查询结果。

参数：

• query（字符串）：要发送给 Codex 的问题或提示
• directory（字符串）：查询的工作目录（默认：当前目录）
• format（字符串）：输出格式 —— "text"、"json" 或 "code"（默认："json"）
• timeout（整数，可选）：超时时间（秒）（推荐：60 - 120，默认：90）

示例：

consult_codex(
    query="Find authentication patterns in this codebase",
    directory="/path/to/project",
    format="json",  # 默认格式
    timeout=90      # 默认超时时间
)

consult_codex_with_stdin

这是一个支持通过标准输入内容进行管道式执行的 CLI 桥接工具。

参数：

• stdin_content（字符串）：作为标准输入管道的内容（文件内容、差异、日志）
• prompt（字符串）：处理标准输入内容的提示信息
• directory（字符串）：查询的工作目录
• format（字符串）：输出格式 —— "text"、"json" 或 "code"（默认："json"）
• timeout（整数，可选）：超时时间（秒）（推荐：60 - 120，默认：90）

consult_codex_batch

用于批量处理多个查询，非常适合 CI/CD 自动化。

参数：

• queries（列表）：包含查询字典的列表，每个字典包含 'query' 和可选的 'timeout'
• directory（字符串）：所有查询的工作目录
• format（字符串）：输出格式 —— 目前批量处理仅支持 "json"

示例：

consult_codex_with_stdin(
    stdin_content=open("src/auth.py").read(),
    prompt="Analyze this auth file and suggest improvements",
    directory="/path/to/project",
    format="json",  # 默认格式
    timeout=120     # 复杂分析的自定义超时时间
)

💻 使用示例

基础代码分析

# 简单的研究查询
consult_codex(
    query="What authentication patterns are used in this project?",
    directory="/Users/dev/my-project"
)

详细文件审查

# 分析特定文件
with open("/Users/dev/my-project/src/auth.py") as f:
    auth_content = f.read()
    
consult_codex_with_stdin(
    stdin_content=auth_content,
    prompt="Review this file and suggest security improvements",
    directory="/Users/dev/my-project",
    format="json",  # 结构化输出
    timeout=120     # 为详细分析留出更多时间
)

批量处理

# 一次性处理多个查询
consult_codex_batch(
    queries=[
        {"query": "Analyze authentication patterns", "timeout": 60},
        {"query": "Review database implementations", "timeout": 90},
        {"query": "Check security vulnerabilities", "timeout": 120}
    ],
    directory="/Users/dev/my-project",
    format="json"  # 批量处理始终使用 JSON 格式
)

🏗️ 架构

核心设计

• 以 CLI 为先：直接通过子进程调用 codex 命令
• 无状态：每个工具调用都是独立的，无会话状态
• 可配置超时：默认执行时间为 90 秒（可配置）
• 结构化输出：默认使用 JSON 格式，便于更好地集成
• 简单的错误处理：采用快速失败策略，提供清晰的错误信息

项目结构

codex-bridge/
├── src/
│   ├── __init__.py              # 入口点
│   ├── __main__.py              # 模块执行入口点
│   └── mcp_server.py            # 主要的 MCP 服务器实现
├── .github/                     # GitHub 模板和工作流
├── pyproject.toml              # Python 包配置
├── README.md                   # 本文件
├── CONTRIBUTING.md             # 贡献指南
├── CODE_OF_CONDUCT.md          # 社区标准
├── SECURITY.md                 # 安全策略
├── CHANGELOG.md               # 版本历史
└── LICENSE                    # MIT 许可证

🔧 开发

本地测试

# 以开发模式安装
pip install -e .

# 直接运行
python -m src

# 测试 CLI 可用性
codex --version

与 Claude Code 集成

通过 MCP 协议正确配置后，服务器会自动与 Claude Code 集成。

🔍 故障排除

CLI 不可用

# 安装 Codex CLI
npm install -g @openai/codex-cli

# 进行身份验证
codex auth login

# 测试
codex --version

连接问题

• 验证 Codex CLI 是否已正确进行身份验证
• 检查网络连接
• 确保 Claude Code 的 MCP 配置正确
• 检查 codex 命令是否在你的 PATH 中

常见错误信息

• "CLI not available"：Codex CLI 未安装或不在 PATH 中
• "Authentication required"：运行 codex auth login
• "Timeout after X seconds"：查询耗时过长，尝试增加超时时间或将其拆分为更小的部分

🤝 贡献

我们欢迎社区的贡献！请阅读我们的 贡献指南，了解如何开始贡献。

快速贡献指南

1. 分叉仓库
2. 创建功能分支
3. 进行更改
4. 如有必要，添加测试
5. 提交拉取请求

📄 许可证

本项目采用 MIT 许可证 —— 详情请参阅 LICENSE 文件。

🔄 版本历史

详细的版本历史请参阅 CHANGELOG.md。

🆘 支持

• 问题反馈：通过 GitHub 问题 报告错误或请求功能
• 讨论：加入社区讨论
• 文档：可在 docs/ 目录中创建额外的文档

重点：通过官方 CLI，在 Claude Code 和 Codex AI 之间建立一个简单、可靠的桥梁。