Integrate and use codex-cli MCP server effectively with Claude Code. Use when executing shell commands, running builds, or performing file operations through the codex-cli MCP tool. Handles skill loading, command execution, and result processing.
codex-cli (@openai/codex-shell-tool-mcp)
├── Type: Shell Execution Tool (NOT AI Model)
├── Function: mcp__codex-cli__shell
├── Capability: Execute shell commands
└── Limitation: No AI prompting capability
| 구분 | gemini-cli | codex-cli |
|---|---|---|
| 타입 | AI Model MCP | Shell Tool MCP |
| AI 응답 | ✅ 가능 | ❌ 불가능 |
| 스킬 처리 | 자체 처리 | Claude가 처리 |
| 용도 | AI 질의 | 명령 실행 |
패턴 A: 스킬 읽기 → Claude 처리 → codex-cli 실행
1. Claude가 스킬 파일 읽기 (Read tool)
2. 스킬 내용 기반으로 작업 계획 수립
3. codex-cli로 명령 실행
4. 결과 분석 및 다음 단계 진행
예시:
사용자: "api-design 스킬을 참조해서 새 API 엔드포인트 생성해줘"
Claude 처리:
1. Read: .agent-skills/backend/api-design/SKILL.md
2. 스킬 내용 분석 및 코드 생성
3. codex-cli: 파일 생성 및 테스트 실행
기본 사용법:
// MCP 도구 호출
mcp__codex-cli__shell({
command: "npm run build",
workdir: "/path/to/project"
})
응답 형식:
{
"exit_code": 0,
"output": "Build successful",
"duration": {"secs": 5, "nanos": 123456789},
"timed_out": false
}
Infrastructure 스킬 예시:
1. 스킬 로드: infrastructure/system-environment-setup
2. Claude가 스킬 분석
3. codex-cli로 Docker Compose 실행:
- docker-compose up -d
- docker-compose logs
- docker-compose ps
Code Quality 스킬 예시:
1. 스킬 로드: code-quality/code-review
2. Claude가 리뷰 기준 확인
3. codex-cli로 린트/테스트 실행:
- npm run lint
- npm run test
- npm run type-check
codex-cli 실행
↓
exit_code 확인
↓
├── 0 (성공): 다음 단계 진행
├── 1 (실패): 오류 분석 후 수정
└── timeout: 명령 최적화 또는 분할
sequenceDiagram
participant U as User
participant C as Claude Code
participant S as SKILL.md
participant X as codex-cli
U->>C: 작업 요청
C->>S: Read 스킬 파일
S-->>C: 스킬 내용
C->>C: 스킬 기반 계획 수립
C->>X: shell 명령 실행
X-->>C: 실행 결과
C->>C: 결과 분석
C->>U: 완료 보고
사용자: "infrastructure 스킬을 참조해서 Docker 환경 세팅해줘"
Claude 작업:
1. Read: .agent-skills/infrastructure/system-environment-setup/SKILL.md
2. 스킬의 docker-compose.yml 템플릿 활용
3. Write: docker-compose.yml 생성
4. codex-cli: docker-compose up -d
5. codex-cli: docker-compose ps (상태 확인)
사용자: "code-review 스킬로 이 PR 체크해줘"
Claude 작업:
1. Read: .agent-skills/code-quality/code-review/SKILL.md
2. 리뷰 체크리스트 확인
3. codex-cli: git diff --name-only
4. Read: 변경된 파일들
5. 스킬 기준으로 리뷰 수행
6. codex-cli: npm run lint (자동 검사)
사용자: "deployment 스킬로 스테이징 배포해줘"
Claude 작업:
1. Read: .agent-skills/infrastructure/deployment-automation/SKILL.md
2. 배포 절차 확인
3. codex-cli: npm run build
4. codex-cli: npm run test
5. codex-cli: ./deploy.sh staging
6. 결과 보고
# 올바른 패턴
1. Claude: Read 스킬 파일
2. Claude: 작업 계획 수립
3. codex-cli: 명령 실행
# codex-cli에서 && 사용
npm install && npm run build && npm run test
mcp__codex-cli__shell({
command: "npm run build",
workdir: "/path",
timeout_ms: 60000 // 60초
})
| 작업 유형 | 권장 도구 | 이유 |
|---|---|---|
| AI 질의/분석 | gemini-cli | AI 응답 필요 |
| 창의적 아이디어 | gemini-cli (brainstorm) | 평가 점수 포함 |
| 명령 실행 | codex-cli | 빠른 shell 실행 |
| 파일 조작 | codex-cli 또는 Bash | 직접 실행 |
| 스킬 기반 작업 | Claude + codex-cli | 스킬은 Claude, 실행은 codex |
#mcp #codex-cli #shell #automation #integration