Codex Bridge

Codex Bridge

一个轻量级的MCP（模型上下文协议）服务器，使AI编码助手能够通过官方CLI与OpenAI的Codex AI进行交互。适用于Claude Code、Cursor、VS Code和其他MCP兼容客户端。专为简单、可靠和无缝集成而设计。

✨ 特性

• 直接Codex CLI集成：使用官方Codex CLI实现API零成本
• 简单的MCP工具：基本查询和文件分析的两个核心功能
• 无状态操作：没有会话、缓存或复杂的状态管理
• 生产就绪：具有可配置超时的强大错误处理（默认值：90秒）
• 最小依赖性：只需要 mcp>=1.0.0 Codex CLI
• 轻松部署：支持uvx和传统pip安装
• 通用MCP兼容性：可与任何兼容MCP的AI编码助手配合使用

🚀 快速开始

先决条件

1. 安装Codex CLI:

   npm install -g @openai/codex-cli

1. 通过Codex认证:

   codex

1. 验证安装:

   codex --version

安装

🎯 推荐：PyPI安装

# Install from PyPI
pip install codex-bridge

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

备选方案：来源

# 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

开发安装

# 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

🌐 多客户端支持

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

支持的MCP客户端

• 克劳德代码 ✅ （默认）
• 光标 ✅
• VS代码 ✅
• 帆板运动 ✅
• 克莱恩 ✅
• 虚空 ✅
• 樱桃工作室 ✅
• 增强 ✅
• Roo代码 ✅
• Zencoder 的 ✅
• 任何兼容MCP的客户端 ✅

配置示例

Claude Code (Default)

# 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

Cursor

全局配置 (~/.cursor/mcp.json):

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

项目特定 (.cursor/mcp.json 在您的项目中）：

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

首选 Settings → Cursor Settings → MCP → Add new global MCP server

VS Code

配置 (.vscode/mcp.json 在您的工作空间中）：

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

替代方案：通过扩展

1. 打开扩展视图（Ctrl+Shift+X）
2. 搜索MCP扩展
3. 使用以下命令添加自定义服务器： uvx codex-bridge

Windsurf

添加到您的Windsurf MCP配置中：

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

Cline (VS Code Extension)

1. 打开Cline并单击 MCP服务器 在顶部导航中
2. 选择 已安装 tab → 高级MCP设置
3. 增添 cline_mcp_settings.json:

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

Void

首选 Settings → MCP → Add MCP Server

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

Cherry Studio

1. 引导到 设置→ MCP服务器→ 添加服务器
2. 填写服务器详细信息：

- 名字: codex-bridge - 类型: STDIO - 命令: uvx - 参数: ["codex-bridge"]

1. 保存配置

Augment

使用UI：

1. 点击汉堡菜单→ 设置 → 工具
2. 点击 +添加MCP 按钮
3. 输入命令： uvx codex-bridge
4. 姓名： Codex Bridge

手动配置：

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

Roo Code

1. 首选 设置→ MCP服务器→ 编辑全局配置
2. 增添 mcp_settings.json:

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

Zencoder

1. 转到Zencoder菜单（…）→ 工具 → 添加自定义MCP
2. 添加配置：

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

1. 点击 安装 按钮

Alternative Installation Methods

对于基于pip的安装：

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

对于开发/本地测试：

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

用于npm风格的安装 （如果需要）：

{
  "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 环境变量。

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

示例配置：

Claude Code

# 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

Manual Configuration (mcp_settings.json)

{
  "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 （string）：发送给Codex的问题或提示
• directory （string）：查询的工作目录（默认：当前目录）
• format （string）：输出格式-“text”、“json”或“code”（默认：“json”）
• timeout （int，可选）：超时秒数（建议：60-120，默认：90）

例子：

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

带有stdin内容的CLI桥，用于管道友好的执行。

参数：

• stdin_content （string）：作为stdin传输的内容（文件内容、差异、日志）
• prompt （string）：处理stdin内容的提示
• directory （string）：查询的工作目录
• format （string）：输出格式-“text”、“json”或“code”（默认：“json”）
• timeout （int，可选）：超时秒数（建议：60-120，默认：90）

consult_codex_batch

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

参数：

• queries （list）：带有“query”和可选“timeout”的查询字典列表
• directory （string）：所有查询的工作目录
• format （string）：输出格式-目前批处理仅支持“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",  # Default format
    timeout=120     # Custom timeout for complex analysis
)

📋 使用示例

基本代码分析

# Simple research query
consult_codex(
    query="What authentication patterns are used in this project?",
    directory="/Users/dev/my-project"
)

详细文件审查

# Analyze specific files
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",  # Structured output
    timeout=120     # Allow more time for detailed analysis
)

批处理

# Process multiple queries at once
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"  # Always JSON for batch processing
)

🏗️ 建筑

核心设计

• CLI优先：直接调用子流程 codex 命令
• 无状态：每个工具调用都是独立的，没有会话状态
• 可配置超时：90秒默认执行时间（可配置）
• 结构化输出：默认为JSON格式，以便更好地集成
• 简单错误处理：使用快速失败方法清除错误消息

项目结构

codex-bridge/
├── src/
│   ├── __init__.py              # Entry point
│   ├── __main__.py              # Module execution entry point
│   └── mcp_server.py            # Main MCP server implementation
├── .github/                     # GitHub templates and workflows
├── pyproject.toml              # Python package configuration
├── README.md                   # This file
├── CONTRIBUTING.md             # Contribution guidelines
├── CODE_OF_CONDUCT.md          # Community standards
├── SECURITY.md                 # Security policies
├── CHANGELOG.md               # Version history
└── LICENSE                    # MIT license

🔧 发展

局部测试

# Install in development mode
pip install -e .

# Run directly
python -m src

# Test CLI availability
codex --version

与Claude Code集成

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

🔍 故障排除

CLI不可用

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

# Authenticate
codex auth login

# Test
codex --version

连接问题

• 验证Codex CLI是否经过正确身份验证
• 检查网络连接
• 确保克劳德代码MCP配置正确
• 检查一下 codex 命令在您的PATH中

常见错误消息

• “CLI不可用”：Codex CLI未安装或不在PATH中
• “需要身份验证”：运行 codex auth login
• “X秒后超时”：查询时间过长，请尝试增加超时时间或拆分为更小的部分

🤝 贡献

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

快速贡献指南

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🔄 版本历史记录

看 更改日志.md 查看详细的版本历史。

🆘 支持

• 问题：通过以下方式报告错误或请求功能
• 讨论：加入社区讨论
• 文档：可以在中创建其他文档 docs/ 目录

______________________________________________________________________

聚焦：通过官方CLI在Claude Code和Codex AI之间建立简单可靠的桥梁。