Skip to main content
Glama
jiwon86

Nano Banana MCP

by jiwon86
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Nano Banana MCP

Google Gemini API의 Nano Banana 이미지 생성 기능을 MCP 서버로 감싼 Python 패키지입니다. Claude Code 같은 MCP 클라이언트에서 바로 연결해 텍스트-투-이미지, 이미지 편집, 검색 그라운딩 워크플로를 사용할 수 있습니다.

  • PyPI: parkjack-nanobanana-mcp

  • GitHub: jiwon86/parkjack-nanobanana-mcp

  • 기본 모델: gemini-3.1-flash-image-preview

  • 추천 실행 방식: uvx

Highlights

  • Claude Code에서 uvx 한 줄로 바로 연결 가능

  • 텍스트 생성과 이미지 편집을 하나의 MCP 툴로 처리

  • gemini-3.1-flash-image-preview, gemini-3-pro-image-preview, gemini-2.5-flash-image 지원

  • 생성 이미지를 로컬 파일로 저장하고 경로, 해시, 메타데이터 반환

  • 웹/이미지 검색 그라운딩 옵션 지원

Related MCP server: gpt-image-2-mcp

Quickstart

Claude Code에서 가장 간단하게 붙이는 방법입니다.

{
  "mcpServers": {
    "nano-banana": {
      "command": "uvx",
      "args": ["parkjack-nanobanana-mcp"],
      "env": {
        "GEMINI_API_KEY": "YOUR_API_KEY",
        "NANOBANANA_DEFAULT_MODEL": "gemini-3.1-flash-image-preview"
      }
    }
  }
}

추가 후 Claude Code 안에서 /mcp로 연결 상태를 확인하면 됩니다.

Installation Options

1. Zero-install with uvx (Recommended)

Python CLI를 설치 없이 실행하고 싶다면 uvx가 가장 깔끔합니다.

{
  "mcpServers": {
    "nano-banana": {
      "command": "uvx",
      "args": ["parkjack-nanobanana-mcp"],
      "env": {
        "GEMINI_API_KEY": "YOUR_API_KEY",
        "NANOBANANA_DEFAULT_MODEL": "gemini-3.1-flash-image-preview"
      }
    }
  }
}

2. Installed CLI

직접 설치한 실행 파일을 쓰고 싶다면:

pip install parkjack-nanobanana-mcp
{
  "mcpServers": {
    "nano-banana": {
      "command": "parkjack-nanobanana-mcp",
      "env": {
        "GEMINI_API_KEY": "YOUR_API_KEY",
        "NANOBANANA_DEFAULT_MODEL": "gemini-3.1-flash-image-preview"
      }
    }
  }
}

3. Local Development

저장소에서 직접 작업하거나 수정하면서 실행하려면:

python3 -m venv .venv
. .venv/bin/activate
pip install -e .

직접 실행:

. .venv/bin/activate
parkjack-nanobanana-mcp

또는:

. .venv/bin/activate
python -m nanobanana_mcp

Configuration

지원 환경 변수:

  • GEMINI_API_KEY: Gemini API 키

  • GOOGLE_API_KEY: GEMINI_API_KEY 대체 키

  • NANOBANANA_DEFAULT_MODEL: 기본 모델 지정

  • NANOBANANA_OUTPUT_DIR: 생성 이미지 저장 디렉터리

  • NANOBANANA_MCP_TRANSPORT: 기본값 stdio, 필요 시 streamable-http

예시:

export GEMINI_API_KEY="YOUR_API_KEY"
export NANOBANANA_DEFAULT_MODEL="gemini-3.1-flash-image-preview"

.env.example도 같이 제공됩니다.

Tooling

nano_banana_generate_image

텍스트 생성과 이미지 편집을 모두 처리하는 메인 툴입니다.

주요 인자:

  • prompt: 생성 또는 편집 지시문

  • image_paths: 입력 이미지 경로 목록. 비우면 text-to-image, 넣으면 image edit

  • model: 사용할 모델. 생략하면 서버 기본값 사용

  • aspect_ratio: 예시 1:1, 16:9, 9:16

  • image_size: 512, 1K, 2K, 4K

  • include_text: 이미지와 함께 텍스트 설명도 받고 싶을 때 사용

  • enable_web_search: 웹 검색 그라운딩

  • enable_image_search: 이미지 검색 그라운딩

  • output_dir: 결과 파일 저장 경로

반환값:

  • 저장된 이미지 절대 경로

  • MIME 타입, 파일 크기, sha256

  • 모델이 함께 반환한 텍스트

  • 사용량 메타데이터

  • 검색 그라운딩 메타데이터

nano_banana_models

지원 모델, 기본 모델, 모델별 제약사항을 반환합니다.

Supported Models

Model

Notes

gemini-3.1-flash-image-preview

기본값. 빠른 이미지 생성과 검색 그라운딩에 적합

gemini-3-pro-image-preview

더 높은 품질과 프롬프트 충실도가 필요할 때 적합

gemini-2.5-flash-image

지원됨. 다만 image_size는 자동 무시

모델 변경 방식:

  1. MCP 툴 호출 시 model 파라미터 직접 지정

  2. 서버 시작 전 NANOBANANA_DEFAULT_MODEL 환경 변수로 기본값 지정

예시:

{
  "prompt": "Create a premium skincare product shot with elegant typography",
  "model": "gemini-3-pro-image-preview",
  "image_size": "2K",
  "include_text": true
}

gemini-2.5-flash-image 예시:

{
  "prompt": "Create a clean app icon of a banana robot on a white background",
  "model": "gemini-2.5-flash-image",
  "aspect_ratio": "1:1",
  "include_text": true
}

Example Prompts

Text-to-image

{
  "prompt": "A premium banana perfume product photo, dramatic studio lighting, elegant glass bottle, white background",
  "aspect_ratio": "1:1",
  "image_size": "2K",
  "include_text": true
}

Image edit

{
  "prompt": "Keep the face unchanged. Turn this into a cinematic profile portrait against a white seamless studio background.",
  "image_paths": ["/absolute/path/to/photo.jpg"],
  "include_text": true
}

Grounded infographic

{
  "prompt": "Visualize today's weather forecast for Seoul as a clean infographic",
  "enable_web_search": true,
  "include_text": true
}

Output

기본적으로 생성 결과는 generated_images/<timestamp>/ 아래에 저장됩니다.

generated_images/
  20260325_130000_123456/
    candidate_00_part_00.png

Operational Notes

  • Google 문서상 생성된 모든 이미지에는 SynthID 워터마크가 포함됩니다.

  • gemini-2.5-flash-image는 지원되지만 image_size는 문서상 미지원이라 자동 무시됩니다.

  • 이미지 검색 그라운딩을 켜면 소스 저작자 표시 요구사항을 지켜야 합니다.

  • 실제 비밀값은 README 예시 그대로 커밋하지 말고, 로컬 설정 또는 비밀 관리 방식으로 넣는 것을 권장합니다.

Verification

실제 API 키 없이 로컬 파이프라인만 확인하려면:

. .venv/bin/activate
python scripts/smoke_mock.py

Publishing

배포 파일 생성:

. .venv/bin/activate
python -m pip install --upgrade build twine
python -m build
python -m twine check dist/*

PyPI 업로드:

python -m twine upload dist/*

업로드 전 체크:

  • PyPI 프로젝트 이름이 비어 있는지 다시 확인

  • 실제 비밀값이 파일에 포함되지 않았는지 확인

  • 새 릴리스를 올릴 때는 pyproject.toml의 version을 먼저 증가

Available Tools

2 tools
nano_banana_generate_imageA

Generate or edit images with Nano Banana.

Pass only prompt for text-to-image generation. Pass image_paths plus prompt for image editing / image-to-image.

ParametersJSON Schema
NameRequiredDescriptionDefault
modelNogemini-3.1-flash-image-preview
promptYes
image_sizeNo
output_dirNo
image_pathsNo
aspect_ratioNo
include_textNo
enable_web_searchNo
request_timeout_sNo
enable_image_searchNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the modal behavior (generation vs editing) but does not mention side effects (e.g., writing to output_dir), rate limits, auth requirements, or what happens with optional flags like web search. This is useful context but lacks depth.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: two short paragraphs that front-load the primary purpose and immediately provide usage modes. Every sentence adds value, with no filler or repetition. This is an exemplar of concise tool documentation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (10 parameters, multiple execution modes, and an output schema), the description is incomplete. It adequately explains the two invocation modes but does not guide the agent on how to choose models, when to set aspect_ratio or image_size, or what the optional boolean flags do. The presence of an output schema reduces the need to explain return values, but the tool's parameter richness demands more guidance than this description provides.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With schema_description_coverage at 0%, the description must compensate for the 10 parameters. It only explains the role of 'prompt' and 'image_paths', leaving the other eight parameters (model, image_size, aspect_ratio, include_text, enable_web_search, request_timeout_s, enable_image_search, output_dir) without any descriptive benefit beyond their schema titles. The two explained parameters are helpful, but the mismatch is significant.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Generate or edit images with Nano Banana', which clearly states the tool's action (generate/edit) and resource (images). It further distinguishes two modes (text-to-image vs image editing) and is unambiguous when compared to the sibling 'nano_banana_models'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly instructs when to pass only 'prompt' versus 'image_paths' plus 'prompt', giving clear context for each invocation mode. However, it does not mention when to prefer an alternative tool or explicitly exclude certain scenarios, so it stops short of a perfect 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

nano_banana_modelsA

Return the supported Nano Banana model ids and usage notes.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must convey safety. 'Return' clearly indicates a read-only operation, and mentioning 'usage notes' hints at practical constraints. It does not explicitly state that no side effects occur, but the semantic is clear enough for a listing tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, concise sentence that front-loads the verb and resource. No wasted words or redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with no parameters and an output schema, so the description's mention of both ids and usage notes is fully adequate. The sibling tool context further clarifies its role.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and schema coverage is 100%. The description adds no parameter details, but none are needed. A baseline of 4 is appropriate for a parameter-free tool.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific action ('Return') and a precise result ('supported Nano Banana model ids and usage notes'). It unambiguously identifies this as a listing/metadata tool, distinct from the sibling generation tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus nano_banana_generate_image is provided. The intended usage is implied (check available models before generation) but not directly stated, so the description earns a mid-level score.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observednano_banana_generate_image
    • First observednano_banana_models
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored across 2 tools

Disambiguation5/5

The two tools are clearly distinct: one provides metadata about available models and usage notes, while the other performs the actual image generation/editing. There is no overlap or ambiguity between them.

Naming Consistency4/5

Both tools share the consistent 'nano_banana_' prefix and use snake_case. 'generate_image' follows verb_noun pattern, while 'models' is a simple plural noun rather than a verb-led name, causing a slight inconsistency.

Tool Count3/5

With only two tools, the surface feels thin, but it is understandable for a narrowly scoped server dedicated to one image generation model. It borders on minimal yet is not unreasonable.

Completeness4/5

The core functionality of generating/editing images is covered, along with model discovery. Missing features like generation history or job status are not obvious gaps for a simple synchronous API, so it is mostly complete.

Resources

Related MCP Connectors

Related MCP Servers