🍌 나노바나나 MCP 설명 및 설치법

📋 개요 및 기능 요약

• Google Gemini 2.5 Flash Image 엔진을 Claude Code 등에서 사용 가능하게 해주는 MCP(Model Context Protocol) 서버
• 주요 기능
  • 자연어 기반 이미지 생성(텍스트→이미지)
  • 기존 이미지 자연어 편집(배경, 디테일 변경)
  • 여러 이미지 블렌딩(합성)
  • 서버/API 사용량 모니터링, 비용 표시
• 기본 지원: PNG/JPEG/WebP, 최대 해상도 1024x1024, 후보 이미지 최대 4개, 평균 비용 $0.039/이미지

🚀 설치법(한글)

권장 방법(pipx)

python -m pip install --user pipx
pipx ensurepath
pipx install nanobanana-mcp

일반 pip 가상환경

python -m venv .venv
source .venv/bin/activate   # (Windows면 .venv/Scripts/activate)
pip install nanobanana-mcp

개발 버전(최신)

 

pip install --index-url https://test.pypi.org/simple/nanobanana-mcp

🔧 Claude Code 연동법

1. Gemini API 키 발급 (Google AI Studio에서 발급)
2. 설정 파일 예시 추가(claude_desktop_config.json):

{
  "mcpServers": {
    "nanobanana": {
      "command": "nanobanana-mcp",
      "args": [],
      "env": {
        "GEMINI_API_KEY": "여기에_API_키_입력"
      }
    }
  }
}

1. Claude Code/데스크톱/CLI 등에서 자연어로 이미지 작업 명령 가능

⚙️ 3. 주요 명령어/파라미터 옵션

카테고리함수 명칭주요 파라미터설명

이미지 생성	nanobanana_generate	prompt(필수), aspect_ratio, style, quality, output_format, candidate_count	자연어 입력→이미지
이미지 편집	nanobanana_edit	image_path(필수), edit_prompt(필수), mask_path	업로드한 이미지에 자연어 편집
이미지 블렌딩	nanobanana_blend	image_paths(필수), blend_prompt(필수), maintain_consistency	여러 이미지 합성(일관성 유지 가능)
서버 상태	nanobanana_status	detailed, include_history, reset_stats	사용량, 상태, 통계 확인

 

• 스타일: photorealistic, digital_art, anime, oil_painting, watercolor 등
• 비율: 1:1, 16:9, 9:16, 4:3 등

🛠️ 4. 문제해결법(FAQ)

• 서버 즉시 종료: API 키 불일치/오류 → 키 재확인, Claude 재시작
• Input validation error: 최신 서버 반영 안 됨 → /mcp 명령 or 데스크톱 재시작
• 이미지 표시 안됨: 경로, 권한, 응답 구조 오류 → 작업 디렉토리, 경로, 파일 확인
• pipx 오류(윈도): pipx ensurepath 후 터미널 재시작
  • 디버깅 모드

NANOBANANA_LOG_LEVEL=DEBUG nanobanana-mcp

or
설정 파일에 "NANOBANANA_LOG_LEVEL": "DEBUG" 추가

• 업데이트
  • pip: pip install --upgrade nanobanana-mcp
  • pipx: pipx upgrade nanobanana-mcp

💡 사용 예시 (기능 시나리오)

• 이미지 생성:
  "선글라스를 쓴 고양이를 해변에서 그려줘"
  "16:9 비율로 일몰이 지는 산 위의 성을 사실적으로 그려줘"
• 이미지 편집:
  "이 사진의 배경을 밤하늘로 바꿔줘"
  "차 색을 빨간색으로 바꿔줘"
• 이미지 블렌딩:
  "이 두 풍경 사진을 하나로 합쳐줘"
  "산과 성 이미지를 블렌딩해서 판타지 풍경 만들어줘"
• 상태 확인:
  "나노바나나 서버 상태 확인해줘"
  "이미지 생성기 사용량 통계 보여줘"

🛠️ 기능 상세 활용 시나리오

• 캐릭터 일관성 워크플로우:
  1. 처음 한 번 구체적으로 프롬프트(설명) 작성해 목표 캐릭터 이미지 생성
  2. 후속 이미지는 "이전 등장 캐릭터와 동일하게"라고 계속 요청해 일관성 유지
• 동화책/시리즈 제작:
  • 한 프롬프트로 시리즈의 메인 캐릭터 및 각장면 생성 → 나중에 GIF 등으로 묶기
• 부분 편집:
  • 이미지 업로드 후 "강아지만 파란 모자로 바꿔줘" 등 타겟 편집 프롬프트 실행
• 블렌딩:
  • 여러 장 이미지를 업로드 후 "두 이미지를 합쳐서 환상적인 새로운 장면 만들어줘" 요청

📁 생성 파일 구조

• outputs/
  • generated/ (신규 생성)
  • edited/ (편집본)
  • blended/ (합성본)
  • metadata.json (메타 정보)

🔎 상세 참고/문제해결

• API Key 오류/누락 → 서버 즉시 종료됨
  ▷ API 키 정확히 입력/갱신, Server & Claude 재시작
• pipx 불가(윈도) → pipx ensurepath, 터미널 재시도
• 사진 안뜸, 경로오류 → 이미지 또는 서버 경로 확인
• 디버그 모드: NANOBANANA_LOG_LEVEL=DEBUG nanobanana-mcp