gpt-image-mcp

Claude Code에 이미지 생성 능력을 부여하세요. "그림 하나 그려 줘"라고 말하면 Claude Code가 대화에서 바로 OpenAI **gpt-image-2**를 사용해 생성합니다 — 앱을 전환하거나 프롬프트를 복사할 필요가 없습니다.

🎯 이게 뭔가요?

Claude Code 사용자용: 이 프로젝트는 gpt-image-2 이미지 생성 기능을 MCP 서버로 Claude Code에 직접 연결합니다. 한 번 설치하고 한 번 등록하면 Claude Code가 네이티브 generate_image 기능을 갖게 됩니다 — 평범한 언어(어떤 언어든)로 이미지를 설명하면 Claude Code가 프롬프트를 만들고, gpt-image-2를 호출하고, 로컬 PNG를 전달합니다. Claude가 설명하는 대신 "그냥 그려 주기"를 원했던 적이 있다면, 이 프로젝트가 바로 그 빠진 조각입니다.

또한 독립형 CLI와 다른 MCP 호스트에서도 작동합니다 — 어디서나 동일한 핵심.

ChatGPT Plus 구독은 필요 없습니다 — gpt-image-2를 지원하는 API 키만 있으면 됩니다.

작동 흐름:

You: "A cyberpunk orange tabby cat in a spacesuit, starfield, cinematic lighting"
  ↓  Claude Code optimizes your prompt into professional English (automatic)
  ↓  gpt-image-mcp calls OpenAI gpt-image-2
  ↓  PNG saved locally → absolute path returned
You: got your image ✓

Related MCP server: gpt-image-mcp

✨ 기능

• Claude Code 네이티브 통합. 한 번 등록하면 Claude Code가 실제 generate_image 도구를 갖게 됩니다 — 평범한 언어로 장면을 설명하면 채팅 안에서 로컬 PNG를 받을 수 있습니다.

• 두 가지 진입점, 하나의 코어. 동일한 생성 로직이 MCP 서버와 일반 CLI 모두에서 작동합니다.

  • gpt-image-mcp --mcp → generate_image / list_images 도구를 제공하는 stdio MCP 서버

  • gpt-image-mcp "a cat in a spacesuit" → 일회성 CLI 생성

• 모든 OpenAI 호환 백엔드. OPENAI_BASE_URL을 원하는 곳으로 지정하세요 (리셀러, 프록시, 자체 호스팅 게이트웨이).

• 품질 등급은 gpt-image-2의 low / medium / high 설정에 매핑됩니다. 추가 모델도, 추가 비용도 없습니다.

• 코드에 키를 넣지 않음. 모든 것이 환경 변수 기반입니다 — 비밀 정보는 저장소에 남지 않습니다.

• 비동기 안전. 이미지는 base64로 디코딩된 PNG로 로컬 디스크에 스트리밍됩니다. API가 직접 디스크에 쓰는 일은 없습니다.

🧰 요구 사항

• Python 3.10+

• OpenAI API 키, 또는 gpt-image-2(또는 GPT_IMAGE_MODEL로 설정한 호환 모델)를 제공하는 OpenAI 호환 엔드포인트(리셀러 / 게이트웨이 / 자체 호스팅).

• pip 또는 uv로 설치 가능한 Python.

📦 설치

PyPI에서

pip install gpt-image-mcp           # pip
# or
uv tool install gpt-image-mcp       # uv

소스에서

git clone https://github.com/Garfield-Wuu/gpt-image-mcp
cd gpt-image-mcp
python -m venv .venv
source .venv/bin/activate           # Windows: .venv\Scripts\activate
pip install -e .

⚙️ 설정

모든 설정은 환경 변수를 통해 이루어집니다:

팁: 기본 베이스 URL은 공식 OpenAI 엔드포인트입니다. 리셀러나 프록시를 사용하려면 OPENAI_BASE_URL을 해당 /v1 루트로 설정하기만 하면 됩니다 — 다른 것은 바뀌지 않습니다.

🚀 사용 방법

MCP 서버로 사용 (Claude Code)

서버를 등록하세요 (~/.venv를 실제 환경 경로로 바꾸세요):

claude mcp add gpt-image -s user \
  --env OPENAI_API_KEY="$OPENAI_API_KEY" \
  --env OPENAI_BASE_URL="$OPENAI_BASE_URL" \
  --env GPT_IMAGE_OUT="$PWD/out" \
  -- gpt-image-mcp --mcp

Claude Code를 다시 시작하면 두 가지 도구를 사용할 수 있습니다:

• generate_image — 이미지를 생성하고 로컬에 저장합니다.

  ┌─────────────────────────────────────────────────────────────┐
  │ "A cyberpunk orange tabby cat in a spacesuit …"             │
  │    → gpt-image-mcp → local PNG → absolute path returned    │
  └─────────────────────────────────────────────────────────────┘

  매개변수: prompt (필수), size, quality, out_name.

• list_images — 이전에 생성한 PNG를 나열합니다(최신순).

Claude Code에서 뭐라고 말할까요:

"사이버펑크 오렌지 태비 고양이가 우주복을 입고, 별이 빛나는 배경, 시네마틱, 고품질로 그려 줘." → generate_image 트리거

"비 내리는 사이버펑크 도시, 네온 반사가 있는 1536x1024 가로 히어로 샷을 생성해 줘." → 크기 + 품질 설정

"전에 생성한 이미지가 뭐야?" → list_images 트리거

특별한 문법은 필요 없습니다 — 어떤 언어든 자신의 말로 이미지를 설명하기만 하면 됩니다. 나머지는 Claude Code가 처리합니다.

CLI로 사용

export OPENAI_API_KEY="sk-..."
gpt-image-mcp "a cyberpunk orange tabby cat, neon rain, cinematic" \
  --size 1536x1024 --quality high --out ./out/hero.png

--no-interactive가 없으면 CLI는 TTY가 있을 때 크기/품질을 대화형으로 선택할 수 있게 해줍니다.

🖼️ 매개변수

size — 캔버스 방향:

quality — gpt-image-2의 자체 품질 설정(단일 모델; 속도/비용과 디테일 사이의 트레이드오프):

🛠️ 개발

pip install -e ".[dev]"
ruff check .            # lint
pytest                  # run tests
python -m build         # build sdist + wheel

구조:

src/gpt_image_mcp/
├── img_core.py    # shared generation logic (no MCP dependency)
├── mcp_server.py  # FastMCP server: generate_image / list_images
└── __main__.py    # CLI + MCP entrypoints

🔐 보안

• 이 패키지에는 API 키가 절대 포함되지 않습니다. 호출 시 OPENAI_API_KEY에서 읽습니다.

• 단일 이미지 생성 요청 외에는 로그에 기록되거나 전송되는 것이 없습니다.

• .env 및 out/ 디렉터리는 기본적으로 git에서 무시됩니다.

📝 참고 사항 및 주의사항

• 각 요청은 엔드포인트와 품질 등급에 따라 일반적으로 ~10–60초 정도 걸립니다.

• 이 프로젝트는 OpenAI와 제휴 관계가 아닙니다; 독립적인 MCP 래퍼입니다.

• gpt-image-2는 기본적으로 이미지를 base64로 반환하며, 이 도구가 디코딩하여 로컬 디스크에 씁니다. url 폴백도 처리됩니다.

📄 라이선스

MIT © Garfield-Wuu.

⭐ 지원

이 프로젝트가 여러분의 시간을 아껴 주었다면, 스타 하나가 큰 힘이 됩니다. 이슈와 PR도 환영합니다.

🌐 다른 언어 / 其他语言

• 中文版 README (README.zh-CN.md) — 简体中文