agency-ai-solutions/openai-codex-mcp

Claude Code와 함께 사용할 수 있도록 OpenAI Codex CLI 도구를 래핑(wrap)하는 MCP 서버입니다.

이 프로젝트는 Claude Code가 OpenAI Codex CLI 도구와 상호작용할 수 있도록 하는 간단한 JSON-RPC 서버를 제공합니다. 이를 통해 Claude Code는 필요할 때 코드 생성, 설명 및 문제 해결을 위해 OpenAI의 모델을 사용할 수 있습니다.

이 MCP 서버는 더욱 직관적이고 강력한 인터페이스를 제공하도록 개선되었습니다:

특화된 메서드 (Specialized Methods): 일반적인 코딩 작업을 위한 전용 메서드를 추가했습니다:
write_code: 지정된 언어로 특정 작업에 대한 코드를 생성합니다.
explain_code: 코드가 어떻게 작동하는지에 대한 상세한 설명을 제공합니다.
debug_code: 문제가 있는 코드에서 버그를 찾아 수정합니다.

모델 선택 (Model Selection): 기본값을 포함하여 명확하게 정의된 모델 옵션을 제공합니다:

• o4-mini

• o4-preview

• o4-pro

• o4-latest

단순화된 구문 (Simplified Syntax): 더 쉬운 통합을 위해 더욱 직관적인 매개변수(parameter) 명명 및 구조를 채택했습니다.

이러한 개선 사항을 통해 Claude Code는 복잡한 프롬프트 엔지니어링 (prompt engineering) 없이도 특정 프로그래밍 작업을 위해 OpenAI의 모델을 더 쉽게 사용할 수 있습니다.

• Python 3.12 이상
• OpenAI Codex CLI 도구 (npm install -g @openai/codex)
• 유효한 OpenAI API 키 (이 서버용이 아닌, Codex CLI용)

이 프로젝트는 PEP-621 pyproject.toml을 사용합니다. 다음 단계를 따르세요:

# 1. 가상 환경 (venv) 생성 및 활성화
uv venv # .venv/ 디렉토리를 생성합니다
source .venv/bin/activate # Windows의 경우: .\.venv\Scripts\activate
...

설치 후, codex_server 엔트리포인트 (entrypoint)를 PATH에서 사용할 수 있습니다.

제공된 설정 스크립트를 사용하여 환경을 자동으로 설정하고 서버를 시작하세요:

./setup_and_run.sh

이 스크립트는 다음을 수행합니다:

• codex CLI 설치 여부 확인
• 필요한 경우 Python 가상 환경 (virtual environment) 설정
• 사용 가능한 경우 Claude CLI를 통해 MCP 도구 설치
• MCP 서버 시작

서버를 수동으로 시작하려면 다음을 수행하세요:

• Codex CLI가 설치되어 있고 OpenAI API 키로 적절히 구성되었는지 확인하세요.
• 서버를 시작합니다: codex_server

또는 uvicorn을 직접 사용하세요: uvicorn codex_server:app

MCP 서버가 실행되면, 다음 두 가지 방법 중 하나를 사용하여 Claude Code에 등록할 수 있습니다:

이 저장소에는 Claude CLI를 사용하여 직접 설치할 수 있는 설정 파일이 포함되어 있습니다:

# JSON 설정에서 MCP 도구를 직접 설치
claude mcp add /path/to/openai_codex_mcp.json
# 도구가 올바르게 설치되었는지 확인
...

또는, 도구를 수동으로 등록할 수도 있습니다:

• Claude Code에서 다음 경로로 이동합니다:
  Settings (설정) → Tools (도구) → Manage MCP Tools (MCP 도구 관리).
• 다음 정보로 새 도구를 생성합니다:
  Name (이름):openai_codex

Description (설명):OpenAI Codex CLI integration via MCP server (MCP 서버를 통한 OpenAI Codex CLI 통합)

Base URL (기본 URL):http://localhost:8000/

Protocol (프로토콜):JSON-RPC 2.0

Authentication (인증):공란으로 남겨둠

• 도구를 저장합니다.

이제 Claude Code는 다른 관점이나 접근 방식이 필요한 작업에 OpenAI Codex CLI 도구를 사용할 수 있습니다. 특정 작업에 OpenAI 모델을 사용하도록 Claude에게 요청함으로써 이를 호출할 수 있습니다.

MCP 서버는 다양한 코딩 작업을 위해 OpenAI 모델과 상호작용할 수 있는 여러 메서드를 제공합니다.

OpenAI에 유연하고 맞춤화된 프롬프트를 보내는 경우:

curl -X POST http://localhost:8000/ \
-H 'Content-Type: application/json' \
-d '{
...

언어 사양을 포함한 코드 생성(Code Generation)을 위한 특화된 메서드:

curl -X POST http://localhost:8000/ \
-H 'Content-Type: application/json' \
-d '{
...

코드 설명(Code Explanation)을 위한 특화된 메서드:

curl -X POST http://localhost:8000/ \
-H 'Content-Type: application/json' \
-d '{
...

버그 찾기 및 수정(Finding and Fixing Bugs)을 위한 특화된 메서드:

curl -X POST http://localhost:8000/ \
-H 'Content-Type: application/json' \
-d '{
...

o4-mini
: 더 빠르고 저렴한 추론 모델 (Reasoning Model)

o3
: 가장 강력한 추론 모델

o3-mini
: o3의 소형 모델 대안

o1
: 이전의 전체 o-시리즈 추론 모델

o1-mini
: o1의 소형 모델 대안

o1-pro
: 더 나은 응답을 위해 더 많은 연산 자원(Compute)을 사용하는 o1 버전

gpt-4.1
: 복잡한 작업을 위한 플래그십 GPT 모델

gpt-4o
: 빠르고 지능적이며 유연한 GPT 모델

gpt-4.1-mini

: 지능, 속도, 비용의 균형을 맞춘 모델

gpt-4.1-nano
: 가장 빠르고 비용 효율적인 GPT-4.1 모델

gpt-4o-mini
: 특정 작업에 집중하기 위한 빠르고 저렴한 소형 모델

prompt

(필수): Codex로 보낼 프롬프트 (Prompt)

model

(선택): 사용할 모델 (예: "o4-mini", "o3", "gpt-4.1", "gpt-4o-mini")

images

(선택): 포함할 이미지 경로 또는 데이터 URI (Data URI) 목록

additional_args

(선택): Codex에 전달할 추가 CLI 인자 (Arguments)

task

(필수): 코딩 작업에 대한 설명

language

(필수): 솔루션을 위한 프로그래밍 언어 (예: "python", "javascript", "java")

model

(선택): 사용할 모델

code

(필수): 설명할 코드

model

(선택): 사용할 모델

code

(필수): 디버깅할 코드

issue_description

(선택): 문제 또는 오류에 대한 설명

model

(선택): 사용할 모델

설정이 완료되면, 사용 가능한 모든 방법 중 하나를 사용하여 Claude에게 특정 작업을 위해 OpenAI Codex를 사용하도록 요청할 수 있습니다:

사용자: OpenAI Codex를 사용하여 소수를 생성하는 Python 함수를 작성해 줄 수 있나요?
Claude: 해당 함수를 생성하기 위해 OpenAI Codex의 write_code 메서드를 사용하겠습니다.
[Claude는 task="Write a Python function that generates prime numbers" 및 language="python"과 함께 write_code 메서드를 사용합니다]

사용자: OpenAI Codex에게 이 퀵 정렬 (Quicksort) 알고리즘이 어떻게 작동하는지 설명해 달라고 요청할 수 있나요?
Claude: 이 알고리즘을 설명하기 위해 OpenAI Codex를 사용하겠습니다.
[Claude는 제공된 code와 함께 explain_code 메서드를 사용합니다]

사용자: 제 JavaScript 함수에 버그가 있습니다. OpenAI Codex를 사용하여 이를 디버깅해 줄 수 있나요?
Claude: 귀하의 코드에서 버그를 찾아 수정하도록 OpenAI Codex에게 요청하겠습니다.
[Claude는 제공된 code와 함께 debug_code 메서드를 사용합니다]

사용자: o4-preview 모델과 함께 OpenAI Codex를 사용하여 이진 탐색 트리 (Binary Search Tree)의 효율적인 구현을 작성해 줄 수 있나요?
Claude: 해당 구현을 생성하기 위해 o4-preview 모델을 사용하겠습니다.
[Claude는 적절한 메서드와 함께 지정된 모델을 사용합니다]

이를 통해 공통적인 코딩 작업에 특화된 메서드와 함께, 동일한 인터페이스 내에서 Claude와 OpenAI의 역량을 모두 원활하게 활용할 수 있습니다.