eLyiN/codex-bridge

AI 코딩 어시스턴트가 공식 CLI를 통해 OpenAI의 Codex AI와 상호작용할 수 있도록 지원하는 경량 MCP (Model Context Protocol) 서버입니다. Claude Code, Cursor, VS Code 및 기타 MCP 호환 클라이언트와 함께 작동합니다. 단순성, 신뢰성 및 원활한 통합을 위해 설계되었습니다.

직접적인 Codex CLI 통합: 공식 Codex CLI를 사용하여 API 비용 제로간단한 MCP 도구: 기본 쿼리 및 파일 분석을 위한 두 가지 핵심 기능상태 비저장 (Stateless) 운영: 세션, 캐싱 또는 복잡한 상태 관리 없음프로덕션 준비 완료: 구성 가능한 타임아웃(기본값: 90초)을 포함한 견고한 에러 핸들링 (error handling)최소한의 의존성: mcp>=1.0.0 및 Codex CLI만 필요

간편한 배포: uvx 및 전통적인 pip 설치 모두 지원범용 MCP 호환성: 모든 MCP 호환 AI 코딩 어시스턴트와 작동

Codex CLI 설치:npm install -g @openai/codex-cli

Codex 인증:codex

설치 확인:codex --version

🎯 권장 사항: PyPI 설치

# PyPI에서 설치
pip install codex-bridge
# uvx를 사용하여 Claude Code에 추가 (권장)
...

대안: 소스에서 설치

# 저장소 클론 (Clone)
git clone https://github.com/shelakh/codex-bridge.git
cd codex-bridge
...

개발용 설치

# 클론 후 개발 모드로 설치
git clone https://github.com/shelakh/codex-bridge.git
cd codex-bridge
...

Codex Bridge는 모든 MCP 호환 AI 코딩 어시스턴트와 작동합니다 - 동일한 서버가 다양한 설정 방법을 통해 여러 클라이언트를 지원합니다.

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
# 개발용 설치
...

Cursor

전역 설정 (~/.cursor/mcp.json):

{
"mcpServers": {
"codex-bridge": {
...

프로젝트별 설정 (.cursor/mcp.json (프로젝트 내 위치)):

{
"mcpServers": {
"codex-bridge": {
...

다음 경로로 이동: Settings (설정)

→ Cursor Settings (Cursor 설정)

→ MCP

→ Add new global MCP server (새로운 전역 MCP 서버 추가)

VS Code

설정 (.vscode/mcp.json (워크스페이스 내 위치)):

{
"servers": {
"codex-bridge": {
...

대안: 확장을 통한 방법

• 확장(Extensions) 뷰 열기 (Ctrl+Shift+X)
• MCP 확장을 검색
• 다음 명령어로 커스텀 서버 추가:
  uvx codex-bridge

Windsurf

Windsurf MCP 설정에 추가:

{
"mcpServers": {
"codex-bridge": {
...

Cline (VS Code 확장 프로그램)

• Cline을 열고 상단 탐색 바에서 MCP Servers를 클릭 - Installed 탭 선택 → Advanced MCP Settings (고급 MCP 설정) - cline_mcp_settings.json에 추가:

{
"mcpServers": {
"codex-bridge": {
...

Void

다음 경로로 이동: Settings (설정)

→ MCP

→ Add MCP Server (MCP 서버 추가)

{
"mcpServers": {
"codex-bridge": {
...

Cherry Studio

• **Settings (설정) → MCP Servers → Add Server (서버 추가)**로 이동 - 서버 세부 정보 입력:
  Name (이름): codex-bridge

Type (유형): STDIO

Command (명령어): uvx

Arguments (인자): ["codex-bridge"]

• 설정을 저장합니다.

Augment

UI 사용 시:

• 햄버거 메뉴 클릭 → Settings (설정) → Tools (도구) - + Add MCP 버튼 클릭 - 명령어 입력: uvx codex-bridge

• 이름: Codex Bridge

수동 설정:

"augment.advanced": {
"mcpServers": [
{
...

Roo Code

• **Settings (설정) → MCP Servers → Edit Global Config (전역 설정 편집)**로 이동 - mcp_settings.json에 추가:

{
"mcpServers": {
"codex-bridge": {
...

Zencoder

• Zencoder 메뉴 (...)로 이동 → Tools (도구) → Add Custom MCP (커스텀 MCP 추가) - 설정 추가:

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

• Install (설치) 버튼을 누릅니다.

대안 설치 방법

pip 기반 설치의 경우:

{
"command": "codex-bridge",
"args": [],
...

개발/로컬 테스트의 경우:

{
"command": "python",
"args": ["-m", "src"],
...

npm 스타일 설치의 경우 (필요한 경우):

{
"command": "npx",
"args": ["codex-bridge"],
...

어떤 클라이언트든 설정이 완료되면, 동일한 두 가지 도구를 사용하십시오:

일반적인 질문하기: "이 코드베이스에서 어떤 인증 패턴 (authentication patterns)이 사용되고 있나요?"
특정 파일 분석하기: "이 인증 파일들에서 보안 이슈가 있는지 검토해 주세요."

서버 구현은 동일합니다 - 오직 클라이언트 설정만 다릅니다!

기본적으로 Codex Bridge는 모든 CLI 작업에 대해 90초의 타임아웃 (timeout)을 사용합니다. 더 긴 쿼리 (대용량 파일, 복잡한 분석)가 필요한 경우, CODEX_TIMEOUT 환경 변수 (environment variable)를 사용하여 사용자 정의 타임아웃을 설정할 수 있습니다.

기본적으로 Codex CLI는 Git 저장소 (Git repository) 또는 신뢰할 수 있는 디렉토리 내에 있어야 합니다. Git 저장소가 아닌 디렉토리에서 Codex Bridge를 사용해야 하는 경우, CODEX_SKIP_GIT_CHECK 환경 변수를 설정할 수 있습니다.

** ⚠️ 보안 경고**: 디렉토리 구조를 직접 제어할 수 있는 신뢰할 수 있는 환경에서만 이 플래그 (flag)를 활성화하십시오.

설정 예시:

Claude Code

# 사용자 정의 타임아웃(120초)과 함께 추가
claude mcp add codex-bridge -s user --env CODEX_TIMEOUT=120 -- uvx codex-bridge
# Git 저장소 체크를 비활성화하여 추가 (non-git 디렉토리용)
...

수동 설정 (mcp_settings.json)

{
"mcpServers": {
"codex-bridge": {
...

설정 옵션:

CODEX_TIMEOUT:

기본값: 90초 (설정되지 않은 경우)
범위: 모든 양의 정수 (초 단위)
권장사항: 대부분의 쿼리에는 60-120초, 대용량 파일 분석에는 120-300초
유효하지 않은 값: 경고와 함께 90초로 되돌아감 (fall back)

CODEX_SKIP_GIT_CHECK:

기본값: false (Git 저장소 체크 활성화됨)
유효한 값: 체크를 비활성화하기 위한 "true", "1", "yes" (대소문자 구분 없음)
사용 사례: Git 저장소가 아닌 디렉토리에서 작업할 때
보안: 본인이 제어하는 신뢰할 수 있는 디렉토리에서만 사용하십시오.

기본적으로 구조화된 JSON 출력을 제공하며 간단한 쿼리를 위한 직접적인 CLI 브리지 (bridge)입니다.

매개변수 (Parameters):

query

(string): Codex로 보낼 질문 또는 프롬프트 (prompt)
directory

(string): 쿼리를 위한 작업 디렉토리 (Working directory) (기본값: 현재 디렉토리)
format

(string): 출력 형식 (Output format) - "text", "json", 또는 "code" (기본값: "json")
timeout

(int, 선택 사항): 초 단위 타임아웃 (Timeout) (권장: 60-120, 기본값: 90)

예시 (Example):

consult_codex(
query="Find authentication patterns in this codebase",
directory="/path/to/project",
...

파이프라인 친화적인 실행을 위해 stdin 콘텐츠를 사용하는 CLI 브리지 (CLI bridge).

매개변수 (Parameters):

stdin_content

(string): stdin으로 파이프 전달할 콘텐츠 (파일 내용, diff, 로그)
prompt

(string): stdin 콘텐츠를 처리할 프롬프트 (Prompt)
directory

(string): 쿼리를 위한 작업 디렉토리 (Working directory)
format

(string): 출력 형식 (Output format) - "text", "json", 또는 "code" (기본값: "json")
timeout

(int, 선택 사항): 초 단위 타임아웃 (Timeout) (권장: 60-120, 기본값: 90)

CI/CD 자동화에 완벽한 다중 쿼리용 배치 처리 (Batch processing).

매개변수 (Parameters):

queries

(list): 'query'와 선택 사항인 'timeout'을 포함하는 쿼리 딕셔너리(dictionary) 리스트
directory

(string): 모든 쿼리를 위한 작업 디렉토리 (Working directory)
format

(string): 출력 형식 (Output format) - 현재 배치 처리에는 "json"만 지원

예시 (Example):

consult_codex_with_stdin(
stdin_content=open("src/auth.py").read(),
prompt="Analyze this auth file and suggest improvements",
...

# 간단한 조사 쿼리 (Simple research query)
consult_codex(
query="What authentication patterns are used in this project?",
...

# 특정 파일 분석 (Analyze specific files)
with open("/Users/dev/my-project/src/auth.py") as f:
auth_content = f.read()
...

# 여러 쿼리를 한 번에 처리 (Process multiple queries at once)
consult_codex_batch(
queries=[
...

CLI-First: codex 명령어로의 직접적인 서브프로세스 (subprocess) 호출
Stateless: 세션 상태가 없는 독립적인 각 도구 호출 (tool call)
Configurable Timeout: 90초 기본 실행 시간 (설정 가능)
Structured Output: 더 나은 통합을 위한 기본 JSON 형식 출력
Simple Error Handling: fail-fast 접근 방식을 통한 명확한 에러 메시지

codex-bridge/
├── src/
│ ├── __init__.py # 엔트리 포인트 (Entry point)
...

# 개발 모드로 설치
pip install -e .
# 직접 실행
...

서버는 MCP (Model Context Protocol) 프로토콜을 통해 적절히 설정되면 Claude Code와 자동으로 통합됩니다.

# Codex CLI 설치
npm install -g @openai/codex-cli
# 인증
...

• Codex CLI가 제대로 인증되었는지 확인
• 네트워크 연결 상태 확인
• Claude Code MCP 설정이 올바른지 확인
• codex 명령어가 PATH에 포함되어 있는지 확인

"CLI not available": Codex CLI가 설치되지 않았거나 PATH에 없습니다.
"Authentication required": codex auth login을 실행하세요.

"Timeout after X seconds": 쿼리 시간이 너무 오래 걸렸습니다. 타임아웃 시간을 늘리거나 더 작은 단위로 나누어 시도하세요.

커뮤니티의 기여를 환영합니다! 시작하는 방법에 대한 자세한 내용은 기여 가이드라인 (Contributing Guidelines)을 읽어주세요.

• 저장소 포크 (Fork)
• 기능 브랜치 (Feature branch) 생성
• 변경 사항 적용
• 해당되는 경우 테스트 추가
• 풀 리퀘스트 (Pull request) 제출

이 프로젝트는 MIT 라이선스 하에 라이선스가 부여됩니다 - 자세한 내용은 LICENSE 파일을 참조하세요.

상세한 버전 이력은 CHANGELOG.md를 참조하세요.

Issues: GitHub Issues를 통해 버그를 보고하거나 기능을 요청하세요.
Discussions: 커뮤니티 토론에 참여하세요.
Documentation: 추가 문서는 docs/ 디렉토리에 생성할 수 있습니다.

Focus: 공식 CLI를 통해 Claude Code와 Codex AI 사이를 연결하는 단순하고 신뢰할 수 있는 브리지 (Bridge).