Claude Desktop이나 Claude Code에서 이미지를 생성하고 싶을 때, 대부분 DALL-E나 Stability AI를 먼저 떠올려요. 그런데 Google Gemini 이미지 모델은 어떨까요? Vertex AI가 필요하다고 생각하기 쉽지만, 사실 API 키 하나만으로 충분히 쓸 수 있어요. 오늘은 Google Gemini의 네이티브 이미지 생성 모델을 MCP(Model Context Protocol) 서버로 감싸서, AI 어시스턴트가 바로 이미지를 만들 수 있게 해주는 terrymcpnanobanana 프로젝트를 소개해 드릴게요.

🤔 왜 또 MCP 서버를 만들었을까

기존 이미지 생성용 MCP 서버들은 대부분 OpenAI의 DALL-E나 Stability AI 기반이에요. Google Gemini 모델을 지원하는 MCP 서버는 거의 없었고, 있더라도 Vertex AI 전용이라 GCP 프로젝트 설정이라는 진입 장벽이 있었어요. 그래서 직접 만들었어요. 핵심 목표는 두 가지였어요.

• API 키만으로 바로 사용 가능 — GCP 프로젝트 없이도 Google AI Studio에서 발급한 API 키로 즉시 시작해요
• Flash와 Pro 듀얼 모델 — 빠르고 저렴한 Flash와 최고 품질의 Pro를 런타임에 자유롭게 전환할 수 있어요

🏗️ 아키텍처: 단일 파일의 미학

terrymcpnanobanana의 전체 로직은 server.py 단일 파일에 들어 있어요. FastMCP 프레임워크 위에 Google GenAI SDK를 연결한 구조예요.

terrymcpnanobanana/
├── server.py           # MCP 서버 전체 로직 (FastMCP + Google GenAI SDK)
├── requirements.txt    # 의존성: fastmcp, google-genai, Pillow
├── README.md           # 영문 문서
└── README_ko.md        # 한국어 문서

단일 파일 설계를 선택한 이유가 있어요. MCP 서버는 본질적으로 API 래퍼예요. “모델에 요청을 보내고 결과를 반환한다”는 단순한 파이프라인이죠. 파일을 여러 개로 나누면 오히려 코드 추적이 어려워지고, 단일 파일이면 보안 감사(audit)도 쉽고 전체 동작을 한 눈에 파악할 수 있어요.

내부 구조

server.py 내부는 명확한 계층으로 나뉘어요.

• 상수 정의 — 모델 ID, 유효한 파라미터 값, 기본값을 모듈 상단에 집중해요
• 클라이언트 초기화 — _get_client()로 지연 초기화(lazy init)해요. Vertex AI와 API Key 모드를 자동으로 분기해요
• 유효성 검증 — _validate_params()로 API 호출 전 모든 파라미터를 로컬에서 검증해요
• 설정 빌더 — _build_config()로 모델별 설정 객체를 일관되게 생성해요
• MCP 도구 5개 — 실제 사용자가 호출하는 도구 함수들이에요

🔀 듀얼 모델: Flash vs Pro

이 서버는 두 가지 Google Gemini 이미지 모델을 지원해요. model 파라미터 하나로 런타임에 전환할 수 있어요.

항목	Flash (Nano Banana 2)	Pro (Nano Banana Pro)
모델 ID	gemini-3.1-flash-image-preview	gemini-3-pro-image-preview
속도	~4-6초	~8-12초
기본 비용 (1K)	~$0.067/장	~$0.134/장
해상도	512px, 1K, 2K, 4K	1K, 2K, 4K
종횡비 옵션	14가지	8가지
레퍼런스 이미지	최대 10장	최대 14장
Thinking Mode	지원	미지원
Search Grounding	지원	미지원

일상적인 이미지 생성에는 Flash가 최적이에요. 비용이 Pro의 절반이고 속도는 두 배 빠르거든요. Pro는 고품질이 필요한 최종 결과물에 쓰면 돼요.

🔑 API 키 모드: GCP 프로젝트 없이 시작하기

이 서버의 가장 큰 특징 중 하나가 듀얼 인증이에요. 환경 변수 하나로 Vertex AI 모드와 API 키 모드를 전환할 수 있어요.

API 키 모드 (개발/테스트용)

Google AI Studio에서 API 키를 발급받아 바로 시작할 수 있어요. GCP 프로젝트 설정, 서비스 계정, ADC(Application Default Credentials) 같은 복잡한 과정이 필요 없어요.

# 환경 변수 두 개면 끝
export GOOGLE_GENAI_USE_VERTEXAI=false
export GEMINI_API_KEY=your-api-key-here

Vertex AI 모드 (프로덕션용)

# GCP 프로젝트가 있으면 전체 기능 사용 가능
export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT=your-project-id
export GOOGLE_CLOUD_LOCATION=global

API 키 vs Vertex AI 파라미터 비교

파라미터	Vertex AI	API 키 모드
person_generation	지원	미지원 (자동 스킵)
prominent_people	지원	미지원 (자동 스킵)
output_mime_type	지원 (JPEG/PNG)	미지원 (PNG 고정)
output_compression_quality	지원	미지원
safety_level	지원	지원
thinking_level	지원	지원
use_search	지원	지원

🛠️ 5가지 MCP 도구

서버가 제공하는 도구는 5가지예요. Claude Desktop이나 Claude Code에서 자연어로 호출할 수 있어요.

1. generate_image — 텍스트로 이미지 생성

텍스트 프롬프트를 입력하면 이미지를 생성해요. 가장 기본적이고 자주 쓰는 도구예요.

# 기본 사용
prompt: "벚꽃이 만개한 일본 정원의 석양 풍경"
model: "flash"
aspect_ratio: "16:9"
image_size: "4K"

# Thinking Mode로 구도 향상 (Flash 전용)
thinking_level: "High"

# Google Search로 실제 장소 정확하게 묘사 (Flash 전용)
use_search: true

2. edit_image — 기존 이미지 편집

기존 이미지를 자연어 지시로 편집해요. 스타일 변환, 배경 제거, 색상 조정 등이 가능해요.

image_path: "/home/user/photo.jpg"
instruction: "수채화 스타일로 변환해 주세요"

3. generate_with_references — 레퍼런스 기반 생성

레퍼런스 이미지를 함께 제공해서 캐릭터 일관성이나 스타일 매칭을 유지할 수 있어요. Flash는 최대 10장, Pro는 최대 14장의 레퍼런스를 지원해요.

prompt: "같은 캐릭터가 카페에서 커피를 마시는 장면"
reference_paths: ["/path/to/char_ref1.png", "/path/to/char_ref2.png"]
model: "pro"    # Pro는 최대 14장 레퍼런스

4. list_generated_images — 생성 이력 조회

출력 디렉토리에 저장된 이미지 목록을 최신순으로 보여줘요. 파일명, 경로, 크기, 수정 시간을 확인할 수 있어요.

5. get_supported_options — 파라미터 레퍼런스

두 모델이 지원하는 모든 파라미터, 유효 값, 기본값을 JSON으로 반환해요. AI 어시스턴트가 이 도구를 먼저 호출해서 사용 가능한 옵션을 파악한 뒤 이미지를 생성하는 패턴이 효과적이에요.

🧠 Flash 전용 기능: Thinking Mode와 Search Grounding

다른 이미지 생성 MCP 서버에 없는 기능 두 가지가 있어요. 둘 다 Flash 모델 전용이에요.

Thinking Mode

thinking_level을 "High"로 설정하면, 모델이 이미지를 생성하기 전에 구도와 구성을 추론해요. “이 장면에서 빛은 어디서 오는 게 자연스러울까”, “원근법은 어떻게 적용할까” 같은 사고 과정을 거친 후 이미지를 만들어요.

Search Grounding

use_search: true로 설정하면, 모델이 Google 검색(웹 + 이미지)을 참조해서 이미지를 생성해요. 실존 인물, 장소, 브랜드 로고 같은 현실 세계 대상을 정확하게 묘사해야 할 때 유용해요.

🛡️ 2중 안전 시스템

이미지 생성에서 안전 필터링은 중요한 문제예요. 이 서버는 2중 안전 시스템을 운영해요.

1단계: Safety Filter (사용자 제어 가능)

safety_level 파라미터로 필터링 강도를 조절할 수 있어요.

• BLOCK_LOW_AND_ABOVE — 가장 엄격 (낮은 수준 유해 콘텐츠부터 차단)
• BLOCK_MEDIUM_AND_ABOVE — 중간 수준
• BLOCK_ONLY_HIGH — 높은 수준만 차단 (권장)
• BLOCK_NONE — 필터 비활성화

2단계: Model Guard (우회 불가)

Google 모델 내부에 탑재된 가드레일이에요. safety_level을 BLOCK_NONE으로 설정해도 이 가드는 작동해요. 불법 콘텐츠나 심각한 유해 콘텐츠는 모델 자체가 생성을 거부해요.

⚡ 최적화: PNG에서 JPEG로

이미지 파일 크기는 실제 운영에서 중요한 문제예요. Google 모델은 기본적으로 PNG로 이미지를 반환하는데, 일반적인 1K 이미지의 경우 약 5.5MB 정도 돼요. Vertex AI 모드에서는 output_mime_type을 "image/jpeg"로, output_compression_quality를 85로 설정해서 약 80%의 파일 크기 절감을 달성해요 (5.5MB에서 500~900KB로). 육안으로 품질 차이를 느끼기 어려운 수준이에요.

💰 해상도별 가격 비교

이미지 한 장당 대략적인 비용이에요 (2026년 2월 기준, 프리뷰 가격).

해상도	Flash	Pro
512px	~$0.045	N/A
1K	~$0.067	~$0.134
2K	~$0.101	~$0.134
4K	~$0.151	~$0.240

Flash 1K 기준 장당 약 7센트예요. DALL-E 3의 장당 $0.04~$0.08과 비슷한 수준이지만, Thinking Mode와 Search Grounding이라는 고유 기능이 있다는 점을 고려하면 경쟁력 있는 가격이에요.

⚙️ Claude Desktop/Code에 연결하기

실제로 사용하려면 MCP 클라이언트 설정 파일에 서버를 등록하면 돼요.

Claude Desktop (API 키 모드)

{
  "mcpServers": {
    "nanobanana": {
      "command": "python",
      "args": ["/path/to/terrymcpnanobanana/server.py"],
      "env": {
        "GOOGLE_GENAI_USE_VERTEXAI": "false",
        "GEMINI_API_KEY": "your-api-key-here",
        "NANOBANANA_OUTPUT_DIR": "/path/to/output/folder"
      }
    }
  }
}

Claude Desktop (Vertex AI 모드)

{
  "mcpServers": {
    "nanobanana": {
      "command": "python",
      "args": ["/path/to/terrymcpnanobanana/server.py"],
      "env": {
        "GOOGLE_CLOUD_PROJECT": "your-project-id",
        "GOOGLE_CLOUD_LOCATION": "global",
        "GOOGLE_GENAI_USE_VERTEXAI": "true",
        "NANOBANANA_OUTPUT_DIR": "/path/to/output/folder"
      }
    }
  }
}

설정 후 Claude에게 “벚꽃이 만개한 일본 정원 그려줘”라고 말하면 바로 이미지가 생성돼요.

🆚 기존 MCP 서버와 뭐가 다를까

이미지 생성 MCP 서버 생태계에서 terrymcpnanobanana의 차별점을 정리해 볼게요.

기능	terrymcpnanobanana	일반 MCP 서버
Thinking Mode	지원 (Flash)	미지원
Search Grounding	지원 (Flash)	미지원
듀얼 인증	Vertex AI + API Key	단일 인증
듀얼 모델	Flash + Pro 런타임 전환	단일 모델
레퍼런스 기반 생성	최대 14장	대부분 미지원
로컬 파라미터 검증	API 호출 전 검증	API 에러에 의존
코드 구조	단일 파일 (감사 용이)	다중 파일

🎨 실제 생성 결과 비교: Gemini Flash vs xAI Grok

스펙과 가격만으로는 실제 결과물의 느낌을 알 수 없잖아요. 그래서 동일한 프롬프트로 Gemini Flash와 xAI Grok이 어떻게 다른 이미지를 만들어내는지 직접 비교해 봤어요.

비교 1: 애니메이션 스타일 — “마법 작업실에서 디지털 그림을 지휘하는 캐릭터”

프롬프트: “A magical workshop where colorful digital paintings float in the air like holograms. An anime-style young woman with long dark hair stands at the center, conducting the floating artworks with glowing fingertips…”

비교 2: 실사 스타일 — “벚꽃 카페에서 말차 라떼를 마시는 여성”

프롬프트: “A young woman with long dark hair sitting in a cozy Japanese cafe by the window. She is holding a warm cup of matcha latte, looking out at cherry blossom trees in full bloom outside…”

비교 인사이트

항목	Gemini Flash	xAI Grok
애니메이션 경향	전통적 애니메이션 스타일에 충실	세미-리얼리스틱 쪽으로 기울어짐
실사 경향	자연스러운 스냅샷 느낌	스튜디오 포트레이트 느낌
색감	프롬프트 색상 지시에 충실	자체적 색 보정 경향 강함
디테일	배경 디테일이 풍부	인물 중심 디테일 강조
비용 (1K)	~$0.067/장	무료 (API 제한 있음)

같은 프롬프트인데도 결과물의 분위기가 확연히 달라요. Gemini Flash는 프롬프트에 더 충실한 결과를 내고, xAI Grok은 자체적인 예술적 해석을 더 가미하는 경향이 있어요. 두 모델 모두 MCP 서버를 통해 같은 워크플로우에서 사용할 수 있으니, 목적에 따라 골라 쓰면 돼요.

📝 정리

terrymcpnanobanana는 Google Gemini의 네이티브 이미지 생성 능력을 MCP 프로토콜로 감싼 서버예요. 핵심을 요약하면 이래요.

• API 키 하나로 시작 — GCP 프로젝트 없이 Google AI Studio API 키만으로 바로 사용 가능해요
• Flash + Pro 듀얼 모델 — 빠르고 저렴한 Flash(~$0.067/장)와 고품질 Pro(~$0.134/장)를 런타임에 전환해요
• Thinking Mode + Search Grounding — 다른 이미지 MCP 서버에서 찾기 어려운 고유 기능이에요
• 단일 파일 설계 — server.py 하나에 모든 로직이 담겨 있어서 이해하기 쉽고 감사하기 편해요
• 5가지 도구 — 생성, 편집, 레퍼런스 기반 생성, 이력 조회, 옵션 조회를 모두 지원해요

MCP 서버 이미지 생성 도구를 찾고 있었는데 OpenAI/Stability AI 외의 선택지가 필요했다면, 한번 시도해 보세요. 특히 Thinking Mode로 구도를 잡고 Search Grounding으로 현실 세계를 정확하게 묘사하는 조합은 다른 서비스에서 경험하기 어려운 워크플로우예요. 프로젝트는 GitHub에서 오픈소스로 공개되어 있어요: github.com/goandon/terrymcpnanobanana