w31r4/codex-mcp-go

codex-mcp-go는 Go 언어로 구현된 MCP (Model Context Protocol) 서버입니다. 이 서버는 OpenAI의 Codex CLI를 캡슐화하여, KiloCode, Roo Code, Cline 등 다양한 "Vibe Coding" AI 클라이언트에서 MCP 도구로 호출할 수 있게 해줍니다.

이 프로젝트의 초기 의도는 매우 간단합니다: 강자는 더 강하게, 전문가는 전문 분야에 집중하게 만드는 것입니다.

저의 개인적인 워크플로우(KiloCode에서 Gemini 3.0 Pro 사용)에서, Gemini와 같은 첨단 모델은 강력한 계획 능력과 상상력을 가지고 있지만, 자신이 생성한 복잡한 코드를 수정할 때 가끔 "막히는" 현상을 발견했습니다. 반면, 노련한 "코드 장인"인 Codex는 거시적인 서사 능력은 다소 떨어질지 몰라도, 구체적인 코드 구현, 버그 수정(Bug Fix), 그리고 정밀한 지시 사항 준수 측면에서는 타의 추종을 불허합니다.

그렇다면, 이들이 협력하게 만들면 어떨까요?

codemcp (Python 구현체)에서 영감을 받아, 제가 더 선호하는 Go 언어를 사용하여 mcp-go-sdk를 배우는 동시에 이 바퀴를 다시 발명하기로 했습니다. 주요 목적은 연습 겸 저 자신에게 더 적합한 도구를 만드는 것입니다.

이제 여러분은 MCP를 지원하는 모든 Vibe Coding 도구에서 단 한 줄의 명령으로, Gemini나 Claude 같은 "사령관"이 Codex라는 "특수 요원"을 호출하여 가장 까다로운 코딩 작업을 완수하게 할 수 있습니다.

주요 특징:

세션 관리 (Session Management): SESSION_ID를 지원하여 다회차 대화의 컨텍text를 유지합니다. 샌드박스 제어 (Sandbox Control): read-only, workspace-write 등 보안 정책을 제공합니다. 동시성 지원 (Concurrency Support): Go 고루틴(Goroutine)을 기반으로 하여 다중 클라이언트의 동시 호출을 지원합니다. 단일 파일 배포 (Single File Deployment): 단일 바이너리 파일로 컴파일되어 런타임 의존성이 없습니다.

본 도구는 OpenAI의 codex CLI에 의존합니다. 반드시 해당 CLI가 설치 및 설정되어 있는지 확인하십시오.

Codex CLI 설치:

# npm을 사용하여 설치 (권장)
npm i -g @openai/codex
# 또는 공식 저장소 참조
...

Go 환경 설치 없이 바로 실행:

npx @zenfun510/codex-mcp-go

Releases 페이지에서 해당 플랫폼의 바이너리 파일을 다운로드하십시오.

Go 1.24+ 환경이 필요합니다.

git clone https://github.com/w31r4/codex-mcp-go.git
cd codex-mcp-go
go build -o codex-mcp-go cmd/server/main.go

사용 중인 AI 클라이언트에 따라 적절한 설정 방식을 선택하십시오.

Claude Code

claude mcp add codex -s user --transport stdio -- npx -y @zenfun510/codex-mcp-go

Roo Code (VSCode / Cursor)

Roo Code의 MCP 설정에 다음을 추가하십시오:

{
"mcpServers": {
"codex": {
...

설정 파일 경로 참고:

• VSCode:
  ~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json

• Cursor:
  ~/.config/Cursor/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json

KiloCode

~/.kilocode/mcp.json에 다음을 추가하십시오:

{
"mcpServers": {
"codex": {
...

Cursor (Native MCP)

• Cursor 설정 열기 -> Features -> MCP
• "Add New MCP Server" 클릭
• 설정 입력:
• Name: codex
• Type: stdio
• Command: npx
• Args: -y @zenfun510/codex-mcp-go

만약 go build를 통해 바이너리 파일을 빌드했다면 (경로가 /path/to/codex-mcp-go라고 가정), 다음 설정을 사용할 수 있습니다:

Claude Code

claude mcp add codex -s user --transport stdio -- /path/to/codex-mcp-go

Roo Code / KiloCode / 일반 JSON 설정

Roo Code / KiloCode / 일반 JSON 설정

{
"mcpServers": {
"codex": {
...

Cursor (네이티브 MCP)

• Cursor 설정 열기 -> Features -> MCP
• "Add New MCP Server" 클릭
• 설정 입력:
  • Name: codex
  • Type: stdio
  • Command: /path/to/codex-mcp-go
  • Args: (비워둠)
  • Name:

cat <<'EOF' | ./codex-mcp-go
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"0.1.0","capabilities":{}}}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
...

initialize 핸드셰이크를 먼저 완료해야 tools/list 호출이 가능합니다.

만약 반환된 JSON 데이터에 codex 도구가 포함되어 있다면, 정상적으로 실행됨을 의미합니다.

TOML 설정 파일 또는 환경 변수를 통해 실행 전략을 조정할 수 있습니다. 우선순위: 기본값 < 설정 파일 < 환경 변수.

./codex-mcp-go --config ./codex-mcp.example.toml
# 또는
CODEX_MCP_CONFIG=./codex-mcp.example.toml ./codex-mcp-go

환경 변수 (설정 파일 덮어쓰기):

CODEX_MCP_SERVER_NAME
/ CODEX_MCP_VERSION
CODEX_DEFAULT_TIMEOUT
/ CODEX_MAX_TIMEOUT
/ CODEX_NO_OUTPUT_TIMEOUT
(단위: 초)CODEX_MAX_BUFFERED_LINES
/ CODEX_EXECUTABLE_PATH
CODEX_ALLOWED_MODELS
/ CODEX_ALLOWED_PROFILES
(쉼표 구분; *는 임의의 값을 허용함을 의미하며, 기본값 공백은 모두 거부함)CODEX_DEFAULT_SANDBOX
/ CODEX_ALLOWED_SANDBOX_MODES
(쉼표 구분)CODEX_ALLOWED_WORK_DIRS
(쉼표 구분 디렉토리 접두사 목록; 공백 = 제한 없음)CODEX_DISABLE_YOLO
(true/false)CODEX_LOG_LEVEL
/ CODEX_LOG_FORMAT
/ CODEX_LOG_OUTPUT
/ CODEX_LOG_FILE

최적의 경험을 얻으려면 사용 중인 클라이언트 유형에 맞는 시스템 프롬프트를 구성하는 것이 좋습니다.

자율적으로 다단계 작업을 계획하고 실행할 수 있는 Agent에 적합합니다.

KiloCode / Roo Code / Cline 사용자에게:
본 프로젝트는 다양한 클라이언트에 대한 사전 설정된 전문가 모드 파일을 제공합니다. 사용 중인 클라이언트를 선택하여 해당 파일을 가져오십시오:

• KiloCode: codex-engineer-kilocode.yaml
• Roo Code: codex-engineer-roocode.yaml
• Cline: codex-engineer-cline.yaml

가져오기 후, 귀하의 클라이언트에 맞춰 정교하게 조정된 "Codex 협업 전문가" 모드를 얻게 됩니다.

Claude Code 또는 수동 설정 사용자에게:
다음 내용을 Agent 설정에 추가하거나 작업의 초기 지침으로 사용하십시오:

상세 프롬프트 펼치기

## Core Instruction for CodeX MCP
어떤 순간에도, 당신은 현재 과정이 codex와 어떻게 협업할 수 있는지, 그리고 Codex가 제공하는 MCP 도구를 객관적이고 포괄적인 분석의 보장으로 어떻게 호출해야 하는지 생각해야 합니다.
여기서 당신은 **반드시** 다음 몇 가지 단계를 수행해야 합니다:
...

IDE 플러그인으로 실행되는 어시스턴트에게 적합합니다. .clinerules (Roo Code) 또는 "Rules for AI" (Cursor)에 추가하는 것을 권장합니다:

규칙 프롬프트 펼치기

# Codex MCP Tool Rules
You have access to the `codex` tool, which wraps the OpenAI Codex CLI. Use it for complex code generation, debugging, and analysis.
## Workflow
...

도구 이름: `codex`

| 파라미터 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
| `PROMPT` | `string` | ✅ | - | Codex에 전달할 지시어 |
| `cd` | `string` | ✅ | - | 작업 디렉토리 경로 |
| `sandbox` | `string` | ❌ | `"read-only"` | 정책: `read-only` / `workspace-write` / `danger-full-access` |
| `SESSION_ID` | `string` | ❌ | `""` | 다회차 대화 (Multi-turn conversation)를 위한 세션 ID |
| `skip_git_repo_check` | `bool` | ❌ | `true` | Git 디렉토리가 아닌 곳에서도 실행 허용 |
| `return_all_messages` | `bool` | ❌ | `false` | 전체 추론 로그 (Reasoning log) 반환 |
| `image` | `[]string` | ❌ | `[]` | 추가 이미지 경로 |
| `model` | `string` | ❌ | `""` | 명시적으로 허용하지 않는 한 기본적으로 금지 |
| `yolo` | `bool` | ❌ | `false` | 모든 확인 절차 건너뛰기 (비대화형) |
| `profile` | `string` | ❌ | `""` | 명시적으로 허용하지 않는 한 기본적으로 금지 |
| `timeout_seconds` | `int` | ❌ | `1800` | Codex 호출 총 타임아웃 (초, 최대 1800) |
| `no_output_seconds` | `int` | ❌ | `0` | 출력이 없는 상태로 해당 초가 경과하면 실행 종료 (0은 비활성화) |

**런타임 동작:** 기본적으로 30분 총 타임아웃(최대 30분)이 적용되며, 출력 없음 감지(Watchdog)는 기본적으로 비활성화되어 있습니다. 오류 발생 줄이나 0이 아닌 종료 코드(Non-zero exit code)가 발생하면, 중단 원인을 파악하기 쉽도록 최근 출력을 포함하여 반환합니다. 네트워크가 느리거나 MCP 클라이언트 자체의 RPC 타임아웃이 짧은 경우, 조기 취소를 방지하기 위해 호출 시 `timeout_seconds=1800`을 유지하십시오.

**기본 정책:** `sandbox=read-only`, `yolo=false`, `skip_git_repo_check=false`가 적용됩니다. `model/profile`은 기본적으로 거부되며 명시적으로 허용해야 합니다. `timeout_seconds=1800`(최대 1800), `no_output_seconds=0`(비활성화)이 기본값입니다.

| 기능 | 공식 Codex CLI | CodexMCP (본 도구) |
|---|---|---|
| 기본 Codex 호출 | ✅ | ✅ |
| 다회차 대화 | ❌ | ✅ (세션 관리를 통해) |
| 추론 상세 추적 | ❌ | ✅ (전체 로그 캡처) |
| 병렬 작업 지원 | ❌ | ✅ (MCP 프로토콜 지원) |
| 에러 처리 | ❌ | ✅ (구조화된 에러 반환) |

| 기능 | Go 버전 (codex-mcp-go) | Python 버전 (codexmcp) |
|---|---|---|
| 배포 | 단일 바이너리 파일, 의존성 없음 | Python 환경 및 의존성 필요 |
| 시작 속도 | 🚀 매우 빠름 | 🐢 비교적 느림 (인터프리터 시작) |
| 리소스 점유 | 📉 낮음 | 📈 높음 |
| 동시성 모델 | Goroutine (효율적) | Threading |
| 적합한 시나리오 | 프로덕션 환경, 로우레벨 서비스 | 2차 개발, 프로토타입 검증 |

**연결 실패**: `codex` CLI가 PATH에 있는지 확인하거나, Go 버전이 1.24 이상인지 확인하십시오. **권한 없음**: 바이너리 파일에 실행 권한이 있는지 확인하십시오 (`chmod +x`). **세션 유실**: 클라이언트가 이전 호출에서 반환된 `SESSION_ID`를 올바르게 전달하고 있는지 확인하십시오.

본 프로젝트는 MIT License 오픈소스 라이선스를 채택합니다.

본 프로젝트는 codexmcp (Python 구현체)에서 영감을 받았습니다. Codex MCP 통합을 탐구하는 데 있어 선구적인 역할을 수행한 GuDaStudio 팀에 감사드립니다.

**관심을 가져주셔서 다시 한번 감사드립니다! Star를 누르는 것도 잊지 마세요~ 🌟**