Develop/MCP

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

소금찍은사과 2025. 9. 5. 18:48
반응형

📋 개요 및 기능 요약

  • 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

 

반응형