openai-codex-mcp

openai-codex-mcp

一个 MCP 服务，用于封装 OpenAI Codex CLI 工具，以便与 Claude Code 配合使用。

概览

本项目提供了一个简单的 JSON-RPC 服务，使 Claude Code 能够与 OpenAI Codex CLI 工具交互。这样，Claude Code 就可以在需要时使用 OpenAI 的模型进行代码生成、解释和问题解决。

视频演示

https://www.loom.com/share/5d9532a79ae24b309af08c1727156f9c?sid=d9277b91-bf8c-43ec-a3c6-dc69fc52e1d2

近期改进

MCP 服务经过增强，提供了更直观、更稳健的接口：

1. 专用方法：为常见编码任务添加了专用方法：

   • write_code：针对指定任务和语言生成代码
   • explain_code：详细解释代码的工作原理
   • debug_code：查找并修复有问题的代码中的 Bug

2. 模型选择：明确列出了可选模型及默认值：

   • o4-mini
   • o4-preview
   • o4-pro
   • o4-latest

3. 语法简化：参数命名和结构更直观，便于集成

这些改进让 Claude Code 能够更轻松地针对特定编程任务使用 OpenAI 的模型，无需进行复杂的提示词工程。

先决条件

• Python 3.12+
• OpenAI Codex CLI 工具（npm install -g @openai/codex）
• 有效的 OpenAI API 密钥（用于 Codex CLI，而非此服务）

安装和设置

本项目使用 PEP‑621 pyproject.toml。请按以下步骤操作：

# 1. Create & activate a venv
uv venv                     # creates a .venv/ directory
source .venv/bin/activate   # on Windows: .\.venv\Scripts\activate

# 2. Install package and dependencies into the venv
uv pip install .

安装后，codex_server 入口点即可在 PATH 中使用。

运行服务

快速开始

使用提供的设置脚本自动设置环境并启动服务：

./setup_and_run.sh

此脚本将：

• 检查是否已安装 codex CLI
• 根据需要设置 Python 虚拟环境
• 如果 Claude CLI 可用，则通过它安装 MCP 工具
• 启动 MCP 服务

手动启动

如果你更愿意手动启动服务：

1. 确保已安装 Codex CLI，并已使用 OpenAI API 密钥正确配置
2. 启动服务：

   codex_server
   

   或者直接使用 uvicorn： uvicorn codex_server:app

与 Claude Code 集成

MCP 服务运行后，你可以通过以下任一方式将其注册到 Claude Code：

方法 1：使用 Claude CLI（推荐）

仓库包含一个配置文件，可通过 Claude CLI 直接安装：

# Install the MCP tool directly from the JSON config
claude mcp add /path/to/openai_codex_mcp.json

# Verify the tool was installed correctly
claude mcp list

方法 2：通过 UI 手动配置

你也可以手动注册此工具：

1. 在 Claude Code 中，前往 Settings → Tools → Manage MCP Tools。
2. 创建新工具，填写：
   • Name：openai_codex
   • Description：OpenAI Codex CLI integration via MCP server
   • Base URL：http://localhost:8000/
   • Protocol：JSON-RPC 2.0
   • Authentication：留空
3. 保存工具。

现在，Claude Code 可以在需要不同视角或方法的任务中使用 OpenAI Codex CLI 工具。你可以要求 Claude 针对特定任务使用 OpenAI 模型来调用该工具。

API 用法

MCP 服务提供了多种方法，可针对不同编码任务与 OpenAI 的模型交互。

方法 1：通用补全

向 OpenAI 发送灵活的自定义提示词：

curl -X POST http://localhost:8000/ \
     -H 'Content-Type: application/json' \
     -d '{
       "jsonrpc": "2.0",
       "method": "codex_completion",
       "params": {
         "prompt": "Write a JavaScript function to sort an array of objects by a property value",
         "model": "o4-mini"
       },
       "id": 1
     }'

方法 2：编写代码

用于指定语言的代码生成专用方法：

curl -X POST http://localhost:8000/ \
     -H 'Content-Type: application/json' \
     -d '{
       "jsonrpc": "2.0",
       "method": "write_code",
       "params": {
         "task": "Calculate the first 100 Fibonacci numbers and return them as an array",
         "language": "python",
         "model": "o4-mini"
       },
       "id": 1
     }'

方法 3：解释代码

代码解释专用方法：

curl -X POST http://localhost:8000/ \
     -H 'Content-Type: application/json' \
     -d '{
       "jsonrpc": "2.0",
       "method": "explain_code",
       "params": {
         "code": "def quicksort(arr):\n    if len(arr) <= 1:\n        return arr\n    pivot = arr[len(arr) // 2]\n    left = [x for x in arr if x < pivot]\n    middle = [x for x in arr if x == pivot]\n    right = [x for x in arr if x > pivot]\n    return quicksort(left) + middle + quicksort(right)",
         "model": "o4-mini"
       },
       "id": 1
     }'

方法 4：调试代码

用于查找并修复 Bug 的专用方法：

curl -X POST http://localhost:8000/ \
     -H 'Content-Type: application/json' \
     -d '{
       "jsonrpc": "2.0",
       "method": "debug_code",
       "params": {
         "code": "function fibonacci(n) {\n  if (n <= 0) return [];\n  if (n === 1) return [1];\n  let sequence = [1, 1];\n  for (let i = 2; i <= n; i++) {\n    sequence.push(sequence[i-2] + sequence[i-1]);\n  }\n  return sequence;\n}",
         "issue_description": "It generates one too many Fibonacci numbers",
         "model": "o4-mini"
       },
       "id": 1
     }'

可用模型

推理模型（O 系列）

• o4-mini：速度更快、价格更实惠的推理模型
• o3：能力最强的推理模型
• o3-mini：o3 的小型模型替代选项
• o1：上一代完整 O 系列推理模型
• o1-mini：o1 的小型模型替代选项
• o1-pro：增加计算资源、以提供更好响应的 o1 版本

GPT Models

• gpt-4.1：适用于复杂任务的旗舰 GPT 模型
• gpt-4o：快速、智能且灵活的 GPT 模型
• gpt-4.1-mini：兼顾智能、速度与成本
• gpt-4.1-nano：速度最快、性价比最高的 GPT-4.1 模型
• gpt-4o-mini：快速、实惠，适用于专注型任务的小型模型

可用参数

通用补全（codex_completion）

• prompt（必填）：要发送给 Codex 的提示词
• model（可选）：要使用的模型（例如，“o4-mini”、“o3”、“gpt-4.1”、“gpt-4o-mini”）
• images（可选）：要包含的图像路径或数据 URI 列表
• additional_args（可选）：要传递给 Codex 的其他 CLI 参数

编写代码（write_code）

• task（必填）：编码任务的说明
• language（必填）：解决方案所用的编程语言（例如，“python”、“javascript”、“java”）
• model（可选）：要使用的模型

解释代码（explain_code）

• code（必填）：要解释的代码
• model（可选）：要使用的模型

调试代码（debug_code）

• code（必填）：要调试的代码
• issue_description（可选）：问题或错误的说明
• model（可选）：要使用的模型

在 Claude Code 中使用示例

配置完成后，你可以通过任何可用方法让 Claude 使用 OpenAI Codex 执行特定任务：

使用 write_code 方法

User: Can you use OpenAI Codex to write a Python function that generates prime numbers?

Claude: I'll use the OpenAI Codex write_code method to generate that function.

[Claude would use the write_code method with task="Write a Python function that generates prime numbers" and language="python"]

使用 explain_code 方法

User: Can you ask OpenAI Codex to explain how this quicksort algorithm works?

Claude: I'll use OpenAI Codex to explain this algorithm.

[Claude would use the explain_code method with the code provided]

使用 debug_code 方法

User: My JavaScript function has a bug. Can you use OpenAI Codex to debug it?

Claude: I'll ask OpenAI Codex to find and fix the bug in your code.

[Claude would use the debug_code method with the code provided]

指定模型

User: Can you use OpenAI Codex with the o4-preview model to write an efficient implementation of a binary search tree?

Claude: I'll use the o4-preview model to generate that implementation.

[Claude would use the specified model with the appropriate method]

这样，你就可以在同一界面中无缝运用 Claude 和 OpenAI 的能力，并使用针对常见编码任务的专用方法。