JinDaGe - codex-bridge MCP Details

article

README

🚀 Codex Bridge

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

🚀 快速开始

前提条件

安装 Codex CLI：
```
npm install -g @openai/codex-cli
```
使用 Codex 进行身份验证：
```
codex
```
验证安装：
```
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 Code（默认）

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

# 开发环境安装方式
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": {}
    }
  }
}

前往：设置 → Cursor 设置 → MCP → 添加新的全局 MCP 服务器

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 扩展）

打开 Cline，点击顶部导航栏中的 MCP 服务器
选择 已安装 选项卡 → 高级 MCP 设置
添加到 cline_mcp_settings.json 中：

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

Void

前往：设置 → MCP → 添加 MCP 服务器

{
  "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": {}
}

点击安装按钮

替代安装方法

基于 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

# 添加自定义超时时间（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

手动配置（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（字符串）：要发送给 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"：查询耗时过长，尝试增加超时时间或将其拆分为更小的部分

🤝 贡献

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

快速贡献指南

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

📄 许可证

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

🔄 版本历史

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

🆘 支持

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

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

codex-bridge