4장: 설치·등록·사용·트러블슈팅¶

코드는 다 짰습니다. 이제 실제로 자기 컴퓨터에 올리고, Claude Code 안에서 도구로 인지시키고, 첫 이미지를 뽑아 봅니다. 마지막에는 막혔을 때 어디부터 점검할지 정리합니다.

4.1 의존성 설치¶

cd image-generator
pip3 install -r requirements.txt

requirements.txt 는 두 줄뿐입니다.

mcp>=1.27.0
pyyaml>=6.0

왜 이렇게 적은가? — 무거운 일은 전부 Codex CLI(외부 프로세스)가 하기 때문입니다. 우리 서버는 그저 메시지 전달자에 가깝습니다.

참고: setup.sh 를 그대로 실행해도 되고(아래 4.2와 같은 일을 합니다), 처음에는 명령을 한 줄씩 손으로 쳐 보면서 단계별로 이해하는 편이 학습에 좋습니다.

4.2 setup.sh 한눈에 보기¶

#!/usr/bin/env bash
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SETTINGS_FILE="$SCRIPT_DIR/../.claude/settings.local.json"

echo "[1/3] Python 패키지 설치..."
pip3 install openai mcp

echo "[2/3] output 디렉터리 생성..."
mkdir -p "$SCRIPT_DIR/output"

echo "[3/3] Codex 토큰 확인..."
# (Codex 인증 상태 점검)

echo "  다음 설정을 $SETTINGS_FILE 에 추가하세요:"
echo '  "mcpServers": {'
echo '    "image-generator": {'
echo '      "command": "python3",'
echo "      \"args\": [\"$SCRIPT_DIR/server.py\"]"
echo '    }'
echo '  }'

세 단계로 끝납니다.

파이썬 패키지 설치
output/ 폴더 만들기
Codex 인증 확인
(수동) Claude Code 의 settings.local.json 에 MCP 서버 등록 안내

스크립트가 settings.local.json 을 직접 고치지 않는 이유는 — 그 파일에 다른 MCP 서버나 권한 설정이 이미 있을 수 있어서, 사용자가 직접 보고 추가하는 편이 안전하기 때문입니다.

4.3 Codex CLI 준비¶

이 서버는 Codex CLI 가 있어야 동작합니다.

# 1) Codex 설치 (Node.js 22+ 필요)
npm install -g @openai/codex
codex --version       # 1.x.x 가 떠야 함

# 2) ChatGPT Plus 계정으로 로그인
codex login           # 브라우저가 열리며 OAuth 진행

로그인이 잘 됐는지 확인:

ls ~/.codex/auth.json   # 이 파일이 있으면 OK

자세한 Codex 사용법은 docs/ai-tools/02-openai-codex.md 참고.

4.3.1 모델 호환성 — 자주 막히는 부분¶

# ~/.codex/config.toml
model = "gpt-5.5"

중요: 어떤 모델은 ChatGPT 계정에서 호출이 막혀 있습니다 (예: gpt-5-mini 는 API 키 전용). ChatGPT Plus 로 쓰려면 Plus가 지원하는 모델이 적혀 있어야 합니다. 이 파일을 손댄 적이 없다면 기본값 그대로 두면 됩니다.

증상이 다음과 같다면 이 줄을 의심하세요.

not supported when using Codex with a ChatGPT account

4.4 Claude Code 에 MCP 서버 등록¶

Claude Code 가 우리 서버를 "어디 있는지" 알게 해 줘야 합니다. 등록은 두 가지 위치 중 하나에 합니다.

위치	적용 범위
`<프로젝트>/.claude/settings.local.json`	이 프로젝트 안에서만
`~/.claude/settings.json`	모든 프로젝트 (전역)

이 수업에서는 프로젝트 로컬 등록을 권장합니다.

{
  "mcpServers": {
    "image-generator": {
      "command": "python3",
      "args": ["/home/leo/development/tutoring/image-generator/server.py"]
    }
  }
}

경로는 절대경로로 적습니다. Claude Code 는 다른 작업 디렉토리에서 이 명령을 실행할 수 있기 때문에, 상대경로로 적으면 못 찾는 사고가 생깁니다.

참고: 이미 .claude/settings.local.json 에 다른 키들(permissions, hooks 등)이 들어 있다면, 그 객체에 mcpServers 키를 합쳐 넣으면 됩니다. 파일을 통째로 덮어쓰지 마세요.

설정을 저장한 뒤 Claude Code 재시작. 새 세션에서 /mcp 를 입력하면 등록된 MCP 서버 목록이 뜨고, image-generator 가 거기 있어야 합니다.

4.5 첫 호출 — "흰 배경 빨간 사과 포스터"¶

Claude Code 안에서 그냥 한국어로 말하면 됩니다.

> 흰 배경에 빨간 사과 포스터 만들어줘

내부에서 일어나는 일:

Claude 가 우리의 instructions 를 읽고 → generate_image 도구를 골라 호출
한국어 요청을 영문 프롬프트로 풀어 씀: "A minimalist poster ... vivid crimson red apple ..."
우리 서버가 _run_codex_imagegen 으로 Codex 서브프로세스 시동
Codex 가 ChatGPT OAuth 로 image_generation 호출
PNG 가 ~/.codex/generated_images/<session>/ig_xxx.png 에 떨어짐
우리 서버가 output/2026-04-25/HHMMSS_<slug>.png 로 사본 + JSON
base64 미리보기를 채팅창으로 전송 → Claude Code 가 인라인 표시

대략 30~60 초쯤 걸립니다. quality="high" 를 "medium" 으로 낮추면 더 빠릅니다.

4.6 자주 쓰는 호출 패턴¶

4.6.1 한 컷 — 빠른 시안¶

> 카페 신메뉴 라떼아트 광고 한 컷

→ generate_image(prompt=..., n=1)

4.6.2 시안 발산 5장¶

> 신메뉴 광고 시안 5장으로 변주해서 보여줘

→ generate_variations(concept=..., n_variations=5) 조명·구도·무드가 1장씩 다르게 나옵니다.

4.6.3 프리셋 적용¶

> 손목시계 럭셔리 다크 톤으로 한 컷

→ generate_image(prompt="luxury wristwatch", preset="luxury_dark")

먼저 어떤 프리셋이 있는지 보고 싶다면:

> 어떤 프리셋 쓸 수 있어?

→ list_presets()

4.6.4 기존 사진 편집¶

> 이 제품 사진의 배경만 깨끗한 화이트 스튜디오로 바꿔줘
> /home/leo/photos/product.jpg

→ edit_image(prompt="Replace background with clean white studio, soft shadow", image_paths=["/home/leo/photos/product.jpg"])

4.7 결과물 살펴보기¶

ls output/2026-04-25/
# 145236_red_apple_poster.png
# 145236_red_apple_poster.json
# 150812_0_coffee_new_product.png
# 150812_0_coffee_new_product.json
# 150812_1_coffee_new_product.png
# 150812_1_coffee_new_product.json
# ...

cat output/2026-04-25/145236_red_apple_poster.json

JSON 메타데이터에는 expanded_prompt 가 그대로 들어 있어, 마음에 든 시안을 발견하면 그 프롬프트를 시드 삼아 다시 변주할 수 있습니다.

4.8 트러블슈팅 가이드¶

4.8.1 `/mcp` 에 image-generator 가 안 보인다¶

.claude/settings.local.json 의 JSON 문법 점검 — 콤마 빠짐, 따옴표 짝이 가장 흔함
args 의 server.py 경로가 절대경로 인지 확인
Claude Code 를 재시작 했는지 (새 세션에서만 다시 읽힘)
python3 /절대경로/server.py 를 직접 실행해 봤을 때 에러 없이 멈춰 있는지(stdio 대기) 확인

4.8.2 "mcp 패키지가 없습니다"¶

pip3 install mcp
# 또는
pip3 install -r image-generator/requirements.txt

여러 파이썬이 깔린 환경이라면 which python3 와 Claude Code 가 부르는 python3 가 같은 인터프리터인지 확인. 다르면 args 의 첫 항목을 /usr/bin/python3 같은 절대경로로 박는 편이 안전합니다.

4.8.3 "이미지가 생성되지 않았습니다"¶

3장에서 짠 친절한 에러 메시지가 그대로 나옵니다. 패턴별 처방:

에러 텍스트	처방
`codex exec 실패 (exit ...)`	출력 끝부분 보고, Codex 자체 이슈인지 확인 (`codex --version`, 업데이트)
`not supported ... ChatGPT account`	`~/.codex/config.toml` 의 `model` 변경
`Codex 인증 만료`	`codex login` 다시
`타임아웃 (240s 초과)`	네트워크 / OpenAI 측 지연. `quality="medium"` 으로 시도.

4.8.4 "n은 1~4 사이여야 합니다"¶

Claude 가 한 번에 너무 많이 만들려고 했을 때 우리 검증에 막힌 경우입니다. 여러 장이 필요하면 generate_variations 를 쓰세요 — 단순 동일 프롬프트 N장보다 변주가 더 유용합니다.

4.8.5 Codex 가 코드를 짜기 시작한다¶

_build_imagegen_prompt 의 안전 문구가 어떤 사유로 무시된 케이스. 거의 발생하지 않지만, 발생 시:

Codex 버전 업데이트 (npm i -g @openai/codex)
프롬프트에 "Use the image_generation tool" 같은 명시 문구가 그대로 들어가 있는지 코드 점검

4.8.6 이미지 인라인 미리보기가 안 뜬다¶

Claude Code 채팅 UI 가 이미지를 표시할 수 있는 환경인지 (CLI/IDE/웹 환경마다 차이가 있음)
결과 PNG 자체는 output/ 에 정상 저장되고 있는지 — 이게 중요합니다. 미리보기는 부가 기능, 파일은 본체.

4.8.7 ChatGPT 쿼터 초과¶

ChatGPT Plus 의 이미지 쿼터는 보통 3시간당 ~50장 수준 (정책에 따라 변동). 초과 시 Codex 가 "한도 초과" 류의 메시지를 주며 PNG가 안 만들어집니다. 3시간 기다리거나 적게 사용하는 식으로 풀립니다.

4.9 보안·운영 점검사항¶

output/ 을 git에 올리지 말 것 — 파일이 커지고 민감한 시안이 섞일 수 있음. .gitignore 권장.
OAuth 토큰 (~/.codex/auth.json) 은 절대 커밋·공유 금지. 이 파일이 곧 사용자의 ChatGPT 세션입니다.
MCP 서버는 stdio 로컬 프로세스라, 네트워크에 노출되지 않습니다 — 그러나 우리 코드가 subprocess.Popen 으로 외부 명령을 실행하는 만큼, prompt 인자에 셸 인젝션 가능성이 없는지 다시 확인. (현재 코드는 create_subprocess_exec 로 인자를 분리해 넘기므로 안전합니다.)

4.10 다음 단계 — 이 도구를 키우는 방향¶

수업 범위는 여기까지지만, 직접 더 키워 볼 수 있는 방향을 몇 가지 적어 둡니다.

아이디어	한 줄 설명
새 프리셋 추가	`presets.yaml` 에 자기 브랜드 톤(예: `my_brand`) 등록
이미지 그리드 합성	`generate_variations` 결과 N장을 자동으로 한 PNG 그리드로 합쳐 비교
텍스트 오버레이	Pillow 로 포스터에 카피 문구 자동 합성
결과 검색 도구	`output/` 의 JSON 메타데이터를 키워드로 뒤져 과거 시안 찾기
다른 백엔드	`fal.ai` 등 유료 API 백엔드를 동일 인터페이스로 추가, `quality="ultra"` 일 때만 사용

특히 마지막 항목이 흥미로운 연습입니다 — MCP 도구의 시그니처는 그대로 두고, 내부 구현만 바꿔 끼우는 식으로 백엔드를 추상화해 보세요. 좋은 인터페이스 설계 연습이 됩니다.

4.11 회고 — 무엇을 배웠나¶

이 미니 프로젝트로 다음을 익혔습니다.

MCP 서버 작성 — FastMCP 데코레이터, stdio 전송, instructions
외부 CLI 래핑 — asyncio subprocess, stdin/stdout 명시 처리, 타임아웃
사이드이펙트 캡처 — stdout 파싱 대신 파일시스템 스냅샷 diff
친절한 에러 분기 — 알려진 실패 패턴을 사용자 처방으로 변환
결과물 박제 — 이미지 옆에 입력 조건 JSON 으로 함께 저장
재사용 가능한 디자인 시스템 — presets.yaml 로 스타일 모듈화

도구를 "쓰는 사람"에서 "만드는 사람"으로 한 발을 옮긴 셈입니다. 다음에 새로운 외부 서비스(이메일·캘린더·DB·내부 사내 API)를 Claude 에 붙이고 싶을 때, 이 코드 200줄의 골격이 거의 그대로 재사용됩니다 — 이름과 도구 본체만 바꾸면 또 다른 MCP 서버가 됩니다.

수고하셨습니다.