NanoBridge

Gemini의 Nano Banana 이미지 생성 기능을 MCP 서버와 CLI로 에이전트에 연결합니다 — 이미지당 과금이 아니라 계정에 이미 있는 Gemini 요금제를 사용합니다.

nanobridge sprite "a small knight with a blue shield and a silver sword" --size 160

두 이미지 모두 이 README의 명령으로 만들어진 결과물입니다 — 스프라이트는 이미 트리밍되고 투명 처리되었으며, 애니메이션은 시트에서 슬라이스되어 루프 GIF로 조립되었습니다.

그냥 API를 호출하면 안 되는 이유

AI Studio API 키가 가장 확실한 방법이지만 무료 요금제에서는 작동하지 않습니다: 무료 티어는 이미지 할당량이 0이기 때문에 모든 이미지 모델이 429 RESOURCE_EXHAUSTED를 반환합니다. 결제를 활성화하면 해결되지만 이미지당 과금이 시작되며, 같은 계정에 이미 있는 Gemini 구독은 사용되지 않은 채 남습니다.

NanoBridge는 다른 문을 사용합니다: Chrome에 이미 있는 __Secure-1PSID 쿠키로 브라우저와 동일하게 인증하여 구독의 할당량을 사용합니다. 붙여넣을 것도, 구매할 것도 없습니다.

nanobridge doctor는 어떤 백엔드가 활성 상태인지와 남은 할당량을 알려줍니다.

Related MCP server: Nano Banana Pro MCP

설치

git clone https://github.com/NspxMiguel/NanoBridge.git
cd NanoBridge && ./install.sh

설치 프로그램은 virtualenv를 만들고 nanobridge를 PATH에 추가하며, MCP 서버를 Claude Code에 등록하고 에이전트 스킬을 설치합니다. Homebrew:

brew install --cask nspxmiguel/tap/nanobridge

요구 사항: Python 3.11+ 및 https://gemini.google.com에 로그인된 브라우저.

셸에서 사용하기

nanobridge doctor                        # backends, quota, config path
nanobridge sprite "a green slime" --style pixel --size 128
nanobridge icon "a compass rose" --style flat
nanobridge gen "a seamless stone wall texture, top-down, tileable"
nanobridge edit hero.png "make the sky stormy, keep everything else"

nanobridge sheet "a green slime" --grid 4x2 \
  --action "squash down and stretch back up, a bouncy idle loop" --fps 10

시트가 생성되고 프레임으로 슬라이스되며 투명도를 유지한 채 루프 GIF로 조립됩니다 — GIF에는 알파 채널이 없으므로 빈 픽셀을 위해 팔레트 인덱스가 예약됩니다.

두 명령은 네트워크에 접속하지 않으므로 할당량을 소모하지 않으며 어디서든 이미지에 작동합니다:

nanobridge cut photo.jpg --transparent --trim --size 256
nanobridge slice sheet.png --grid 6x1 --size 96

에이전트에서 사용하기

MCP 서버는 generate_image, generate_sprite, generate_sprite_sheet, generate_icon, edit_image, cut_image, slice_sheet 및 nanobridge_status를 제공합니다.

모든 생성 도구는 이미지를 모델에게 다시 반환하며, 디스크의 경로와 함께 512px 미리보기로 축소됩니다. 이것이 핵심입니다: 자신이 그린 것을 볼 수 없는 에이전트는 좋은 스프라이트와 깨진 스프라이트를 구분할 수 없으며, 맹목적으로 반복합니다.

수동으로 등록하기:

claude mcp add nanobridge --scope user -- /path/to/.venv/bin/nanobridge mcp

후처리가 하는 일

모델은 평평한 배경 위의 큰 JPEG을 반환합니다. 스프라이트는 그 반대가 필요하므로 파이프라인은 사후 처리 수준이 아니라 도구의 일부입니다:

• 배경 제거는 색상 매칭이 아니라 테두리 연결 방식입니다. 스프라이트 내부의 흰 눈은 뒤의 흰색과 같은 색상입니다; 이미지 테두리에 닿는 영역만 지워집니다.

• 트리밍은 그림에 맞게 크롭합니다.

• 크기 조정은 최근접 이웃 방식입니다. 부드러운 필터로 리샘플링된 픽셀 아트는 더 이상 픽셀 아트처럼 보이지 않습니다.

• 슬라이싱은 기하학적 방식입니다. 프롬프트에서 요청한 그리드가 절단에 사용되는 그리드이며, 개별 프레임이 출력됩니다 — 여기서 모델이 실제로 지시를 따랐는지 확인할 수 있습니다.

언어

화면 텍스트는 포르투갈어와 영어입니다. 시스템 로케일이 기본값을 선택하며, nanobridge lang pt|en으로 선택을 저장하고, NANOBRIDGE_LANG=pt로 한 번의 실행 동안 둘 다를 재정의할 수 있습니다.

알아둘 만한 제한 사항

• 웹 백엔드는 브라우저 세션에 의존합니다. 세션이 만료되면 https://gemini.google.com에서 다시 로그인하세요; nanobridge doctor가 이를 명시적으로 알려줍니다.

• Google이 문서화하지 않은 인터페이스와 통신하므로 Google 측의 변경으로 인해 작동이 중단될 수 있습니다. api 백엔드는 그 자리에 유지되는 대체 수단입니다.

• 생성된 이미지에는 Google의 SynthID 워터마크가 포함됩니다.

라이선스

MIT.