Codex Bridge
一个轻量级的MCP（模型上下文协议）服务器，使AI编码助手能够通过官方CLI与OpenAI的Codex AI进行交互。适用于Claude Code、Cursor、VS Code和其他MCP兼容客户端。专为简单、可靠和无缝集成而设计。
✨ 特性
- 直接Codex CLI集成：使用官方Codex CLI实现API零成本
- 简单的MCP工具：基本查询和文件分析的两个核心功能
- 无状态操作：没有会话、缓存或复杂的状态管理
- 生产就绪：具有可配置超时的强大错误处理（默认值：90秒）
- 最小依赖性：只需要
mcp>=1.0.0Codex CLI - 轻松部署：支持uvx和传统pip安装
- 通用MCP兼容性：可与任何兼容MCP的AI编码助手配合使用
🚀 快速开始
先决条件
- 安装Codex CLI:
npm install -g @openai/codex-cli- 通过Codex认证:
codex- 验证安装:
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 srcCursor
全局配置 (~/.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"]
}
}
}替代方案：通过扩展
- 打开扩展视图（Ctrl+Shift+X）
- 搜索MCP扩展
- 使用以下命令添加自定义服务器：
uvx codex-bridge
Windsurf
添加到您的Windsurf MCP配置中：
{
"mcpServers": {
"codex-bridge": {
"command": "uvx",
"args": ["codex-bridge"],
"env": {}
}
}
}Cline (VS Code Extension)
- 打开Cline并单击 MCP服务器 在顶部导航中
- 选择 已安装 tab → 高级MCP设置
- 增添
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
- 引导到 设置→ MCP服务器→ 添加服务器
- 填写服务器详细信息：
- 名字: codex-bridge - 类型: STDIO - 命令: uvx - 参数: ["codex-bridge"]
- 保存配置
Augment
使用UI：
- 点击汉堡菜单→ 设置 → 工具
- 点击 +添加MCP 按钮
- 输入命令：
uvx codex-bridge - 姓名： Codex Bridge
手动配置：
"augment.advanced": {
"mcpServers": [
{
"name": "codex-bridge",
"command": "uvx",
"args": ["codex-bridge"],
"env": {}
}
]
}Roo Code
- 首选 设置→ MCP服务器→ 编辑全局配置
- 增添
mcp_settings.json:
{
"mcpServers": {
"codex-bridge": {
"command": "uvx",
"args": ["codex-bridge"],
"env": {}
}
}
}Zencoder
- 转到Zencoder菜单（…）→ 工具 → 添加自定义MCP
- 添加配置：
{
"command": "uvx",
"args": ["codex-bridge"],
"env": {}
}- 点击 安装 按钮
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": {}
}普遍使用
一旦配置了任何客户端，请使用相同的两个工具：
- 提出一般性问题：“此代码库中使用了哪些身份验证模式？”
- 分析特定文件：“检查这些身份验证文件是否存在安全问题”
服务器实现完全相同 -只有客户端配置不同！
⚙️ 配置
超时配置
默认情况下，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-bridgeManual 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秒后超时”：查询时间过长，请尝试增加超时时间或拆分为更小的部分
🤝 贡献
我们欢迎社区的贡献！请阅读我们的 贡献指南 了解如何开始的详细信息。
快速贡献指南
- 分叉存储库
- 创建要素分支
- 进行更改
- 如果适用，添加测试
- 提交拉取请求
📄 许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
🔄 版本历史记录
看 更改日志.md 查看详细的版本历史。
🆘 支持
- 问题：通过以下方式报告错误或请求功能
- 讨论：加入社区讨论
- 文档：可以在中创建其他文档
docs/目录
______________________________________________________________________
聚焦：通过官方CLI在Claude Code和Codex AI之间建立简单可靠的桥梁。