1장: Image Generator MCP 서버 — 프로젝트 개요¶

Claude Code 안에서 "포스터 한 장 만들어줘"라고 말하면, 그 말이 그대로 gpt-image-2 호출로 이어지고, 결과 PNG가 output/ 폴더에 떨어지는 작은 도구를 직접 만든다.

1.1 무엇을 만드는가¶

이 수업에서 만들 것은 Image Generator MCP 서버입니다. Claude Code(또는 Claude Desktop)가 자기 안에 "이미지를 만들 줄 아는 도구"를 새로 갖게 되는 일종의 플러그인입니다.

사용자: "흰 배경에 빨간 사과 포스터 만들어줘"
   ↓
Claude Code가 generate_image 도구를 호출
   ↓
MCP 서버(우리가 만들 것)가 실행
   ↓
codex exec 서브프로세스로 gpt-image-2 트리거
   ↓
PNG가 output/2026-04-25/145236_red_apple_poster.png 로 저장

기능은 간단하지만, MCP 서버를 직접 짜고 등록하는 전 과정, 외부 CLI를 서브프로세스로 호출하는 패턴, 결과 파일을 안전하게 캡처하는 트릭까지 모두 다룹니다.

1.2 왜 만드는가 — "API 키 없이" 이미지 생성¶

상용 이미지 생성 서비스는 보통 건당 과금입니다.

서비스	1장 비용 (대략)	결제 방식
OpenAI DALL·E 3 (API)	$0.04 ~ $0.12	API 사용량
fal.ai / replicate	$0.02 ~ $0.10	API 사용량
Midjourney	월 구독 + 쿼터	별도 구독

이미 ChatGPT Plus 구독($20/월)을 쓰고 있다면, 그 구독에 포함된 이미지 생성 쿼터를 그대로 쓰는 편이 가장 싸고 깔끔합니다. 하지만 ChatGPT 구독은 API 키를 발급해 주지 않습니다. 즉, 일반적인 방법으로는 외부 코드에서 그 쿼터를 끌어다 쓸 수 없습니다.

이 프로젝트의 핵심 아이디어는 다음 한 줄입니다.

OpenAI Codex CLI는 ChatGPT 구독 OAuth로 인증한다. 그러니 Codex CLI를 서브프로세스로 호출하면, 우리도 그 인증을 그대로 빌려 쓸 수 있다.

codex exec 명령은 내부에서 image_generation 툴을 호출할 수 있는데, 그 호출은 ChatGPT 구독 쿼터로 처리됩니다. 우리가 직접 OpenAI API를 부르지 않기 때문에 별도 API 키도, 추가 과금도 필요 없습니다.

1.3 MCP가 뭔가 — 30초 요약¶

MCP (Model Context Protocol)는 Anthropic이 만든 "AI에게 도구를 붙이는 표준"입니다. 비유하면 USB 포트와 같습니다.

+----------------+       MCP        +-------------------+
|  Claude Code   | <--------------> |  여러분의 서버     |
|  (호스트)       |    stdio/json    |  (도구 제공자)     |
+----------------+                  +-------------------+
                                          |
                                          | 무엇이든
                                          ↓
                                    DB / API / 파일시스템 /
                                    이번엔 Codex CLI

Claude Code는 MCP 호스트입니다 — 도구를 받아서 쓰는 쪽
우리가 짤 Python 파일은 MCP 서버입니다 — 도구를 제공하는 쪽
둘 사이 통신은 stdio(표준 입출력) 위에 흐르는 JSON 메시지

도구(Tool) 한 개를 선언하는 일은 Python 함수 하나에 데코레이터를 다는 것과 같습니다. (자세한 구조는 2장에서)

1.4 전체 아키텍처 한눈에 보기¶

┌──────────────────────────────────────────────────────────┐
│  Claude Code (호스트)                                      │
│  ─ 사용자 메시지 해석                                       │
│  ─ "이미지 만들어달라" → generate_image 도구 호출 결정       │
└──────────────────────┬───────────────────────────────────┘
                       │ MCP / stdio (JSON)
                       ↓
┌──────────────────────────────────────────────────────────┐
│  server.py  (FastMCP 서버 — 우리가 짤 것)                  │
│  ─ generate_image(prompt, size, quality, ...)             │
│  ─ edit_image(prompt, image_paths, ...)                   │
│  ─ generate_variations(concept, n_variations, ...)        │
│  ─ list_presets()                                         │
└──────────────────────┬───────────────────────────────────┘
                       │ subprocess: codex exec --full-auto ...
                       ↓
┌──────────────────────────────────────────────────────────┐
│  Codex CLI                                                │
│  ─ ~/.codex/auth.json 의 ChatGPT OAuth 토큰 사용          │
│  ─ 내장 image_generation 툴 호출                           │
│  ─ 결과를 ~/.codex/generated_images/<session>/ig_*.png 로  │
│    저장                                                   │
└──────────────────────┬───────────────────────────────────┘
                       │ HTTPS
                       ↓
┌──────────────────────────────────────────────────────────┐
│  OpenAI gpt-image-2  (ChatGPT Plus 쿼터)                  │
└──────────────────────────────────────────────────────────┘

생성된 이미지는 ~/.codex/generated_images/... 에 떨어지는데, 우리는 그걸 프로젝트 안 output/YYYY-MM-DD/ 로 사본 복사하고 옆에 JSON 메타데이터까지 붙여 둡니다. 그래야 "어떤 프롬프트로 만든 사진인지" 나중에 추적할 수 있습니다.

1.5 만들 도구 4개¶

도구 이름	한 줄 설명
`generate_image`	프롬프트 → PNG 1~4장 생성
`edit_image`	기존 이미지 + 변경 지시 → 합성·편집 (image-to-image)
`generate_variations`	한 콘셉트로 조명·구도·무드를 바꿔 여러 시안 발산
`list_presets`	`presets.yaml`에 등록된 브랜드/스타일 프리셋 목록

presets.yaml 에 자주 쓰는 스타일을 미리 적어 두면, 매번 "luxury dark aesthetic, deep black background, dramatic rim lighting..." 을 풀어 쓸 필요 없이 preset="luxury_dark" 한 줄로 끝납니다. 이건 일종의 재사용 가능한 디자인 시스템입니다.

1.6 폴더 구조¶

image-generator/
├── server.py          ← MCP 서버 본체. 도구 4개 + Codex 호출 로직
├── presets.yaml       ← 자주 쓰는 스타일 프리셋
├── requirements.txt   ← mcp, pyyaml
├── setup.sh           ← 설치 스크립트
└── output/            ← 생성된 이미지 + 메타데이터 (자동 생성)
    └── 2026-04-25/
        ├── 145236_red_apple_poster.png
        └── 145236_red_apple_poster.json

의외로 짧습니다. 외부 의존성도 mcp와 pyyaml 두 개뿐입니다. 무거운 일은 전부 Codex CLI에 외주를 맡기기 때문입니다.

1.7 사전 준비물¶

본격적으로 코드를 짜기 전에 다음이 준비되어 있어야 합니다.

Python 3.10+ — python3 --version 으로 확인
Node.js 22+ — Codex CLI가 npm 패키지이기 때문 (node --version)

Codex CLI 설치 + ChatGPT 로그인

npm install -g @openai/codex
codex login        # 브라우저로 ChatGPT Plus 계정 인증

ChatGPT Plus 또는 Pro 구독 — 이미지 쿼터를 쓰려면 필수
Claude Code — 호스트 역할

참고: Codex CLI 자체에 대한 자세한 설명은 docs/ai-tools/02-openai-codex.md 를 참고하세요.

1.8 다음 장 예고¶

장	내용
2장	FastMCP로 서버를 띄우고, 도구 4개를 데코레이터로 등록한다.
3장	`codex exec` 서브프로세스를 어떻게 호출하고, 새로 생긴 PNG를 어떻게 안전하게 캡처하는지 본다.
4장	실제로 설치 → MCP 등록 → Claude Code에서 호출 → 트러블슈팅까지.

도구를 "쓰는 입장"에서 "만드는 입장"으로 한 발 옮기는 수업입니다. 파이썬 200줄로 Claude의 능력을 실제로 확장해 봅시다.