Codex Gemini MCP Server

🌐 Language: 한국어 | English

codex-gemini-mcp

AI 에이전트(Claude, Cursor 등)가 OpenAI Codex CLI와 Google Gemini CLI를 MCP 도구로 직접 호출할 수 있게 해주는 프록시 서버입니다.

주요 기능

• ask_codex — 에이전트가 Codex에게 코드 생성·리팩터링·디버깅을 요청
• ask_gemini — 에이전트가 Gemini에게 분석·요약·코드 리뷰를 요청
• 백그라운드 실행 — 오래 걸리는 작업을 백그라운드로 돌리고, 상태 확인(check_job_status)·대기(wait_for_job)·중단(kill_job)·목록 조회(list_jobs)로 관리
• 멀티모델 오케스트레이션 — 하나의 에이전트가 Codex와 Gemini를 동시에 활용하여 작업 분담 가능

하나의 패키지에서 codex-mcp와 gemini-mcp 두 개의 MCP 서버 바이너리를 제공하며, stdio transport 기반으로 동작합니다.

Requirements

• Node.js 20+
• codex CLI 설치 (npm i -g @openai/codex)
• gemini CLI 설치 (npm i -g @google/gemini-cli)

MCP 서버는 각각의 CLI를 그대로 실행하므로, 먼저 로컬 터미널에서 로그인/인증이 완료되어 codex / gemini CLI를 바로 실행할 수 있는 상태인지 확인하세요.

Install

npm에서 설치(배포된 경우):

npm i -g @donghae0414/codex-gemini-mcp

전역 설치 없이 npx 사용:

npx -y -p @donghae0414/codex-gemini-mcp codex-mcp
npx -y -p @donghae0414/codex-gemini-mcp gemini-mcp

소스에서 설치(개발/테스트):

npm install
npm run build
npm link

클라이언트별 MCP 설정 예시

전역 설치 기준:

{
  "mcpServers": {
    "codex-mcp": {
      "command": "codex-mcp",
      "args": []
    },
    "gemini-mcp": {
      "command": "gemini-mcp",
      "args": []
    }
  }
}

전역 설치 없이 npx 기준:

{
  "mcpServers": {
    "codex-mcp": {
      "command": "npx",
      "args": ["-y", "-p", "@donghae0414/codex-gemini-mcp", "codex-mcp"]
    },
    "gemini-mcp": {
      "command": "npx",
      "args": ["-y", "-p", "@donghae0414/codex-gemini-mcp", "gemini-mcp"]
    }
  }
}

opencode (opencode.json):

{
  "mcp": {
    "codex-mcp": {
      "type": "local",
      "command": ["npx", "-y", "-p", "@donghae0414/codex-gemini-mcp", "codex-mcp"]
    },
    "gemini-mcp": {
      "type": "local",
      "command": ["npx", "-y", "-p", "@donghae0414/codex-gemini-mcp", "gemini-mcp"]
    }
  }
}

클라이언트별 설정 파일 위치(참고):

• Claude Code: 프로젝트 루트 .mcp.json (프로젝트별) 또는 ~/.claude.json (전역)
• Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json
• Claude Desktop (Linux): ~/.config/Claude/claude_desktop_config.json
• opencode: ~/.config/opencode/opencode.json

환경 변수는 셸 프로필(.zshrc 등)에서 자동으로 주입되지 않을 수 있으므로, 가능하면 설정 파일의 env 블록으로 전달하세요.

Default Models

기본 모델은 src/config.ts에 하드코딩되어 있으며, 환경 변수로 override할 수 있습니다.

모델 선택 우선순위: 요청 파라미터 model > 환경 변수 > 하드코딩 기본값

Local development

npm install
npm run build
npm run start:codex
npm run start:gemini

개발 모드:

npm run dev:codex
npm run dev:gemini

Runtime Files

• 기본 런타임 디렉토리: <cwd>/.codex-gemini-mcp/
  • background job 상태: jobs/
  • background job 입출력(content): prompts/
  • 구조화 로깅(JSONL): logs/
• 런타임 경로 override:
  • MCP_RUNTIME_DIR: 런타임 루트 디렉토리
  • MCP_LOG_DIR: 로그 디렉토리

정리(기본 경로 사용 시):

rm -rf .codex-gemini-mcp

Security / Privacy Notes

• background: true(기본값) 요청은 .codex-gemini-mcp/prompts/*content*.json에 prompt/response를 저장합니다.
• 프롬프트에 시크릿(토큰, 비밀번호, 개인 정보 등)을 넣으면 로컬 파일에 남을 수 있습니다.
• 로깅은 기본적으로 본문 미저장이지만, 아래 플래그를 켜면 로그에 텍스트가 포함될 수 있습니다:
  • MCP_LOG_PREVIEW=1
  • MCP_LOG_FULL_TEXT=1

Tool Schemas

ask_codex

• prompt (string, required)
• model (string, optional)
• model은 [A-Za-z0-9][A-Za-z0-9._:-]* 패턴(최대 128자)만 허용
• working_directory (string, optional): CLI 프로세스의 실행 디렉토리(cwd)
• background (boolean, optional, default true)
• reasoning_effort (string, optional: minimal | low | medium | high | xhigh)

ask_gemini

• prompt (string, required)
• model (string, optional)
• model은 [A-Za-z0-9][A-Za-z0-9._:-]* 패턴(최대 128자)만 허용
• working_directory (string, optional): CLI 프로세스의 실행 디렉토리(cwd)
• background (boolean, optional, default true)

wait_for_job

• job_id (string, required, 8자리 hex)
• timeout_ms (number, optional, default 3600000, max 3600000; 3600000 초과 값은 3600000으로 cap)

check_job_status

• job_id (string, required, 8자리 hex)

kill_job

• job_id (string, required, 8자리 hex)
• signal (string, optional: SIGTERM | SIGINT, default SIGTERM)

list_jobs

• status_filter (string, optional: active(spawned/running) | completed | failed(failed/timeout) | all, default active)
• limit (number, optional, default 50)

Runtime Notes

• ask_codex: codex exec --ephemeral 호출 (reasoning_effort 지정 시 -c model_reasoning_effort=... 추가)
• ask_gemini: gemini --prompt <text> 호출
• ask_*는 background 미지정 시 기본 true로 실행
• background: true 호출 시 .codex-gemini-mcp/jobs, .codex-gemini-mcp/prompts에 상태/입출력(content) 파일 저장
• 구조화 로깅(JSONL): .codex-gemini-mcp/logs/mcp-YYYY-MM-DD.jsonl
  • 기본: 메타데이터만 저장 (본