A
licenseNot graded
qualityB
maintenanceMCP server for generating, editing, and processing images via multiple providers including Kilo, OpenRouter, OpenAI, and Gemini, with local tools for background removal, resizing, and cropping.
19 npm
3
MIT
mcp-alphabanana
by tasopen
mcp-alphabanana
English | 日本語
mcp-alphabanana는 Google Gemini를 사용하여 이미지 에셋을 생성하기 위한 모델 컨텍스트 프로토콜(MCP) 서버입니다. 빠른 이미지 생성, 투명 출력, 참조 이미지 가이드 및 유연한 전달 형식이 필요한 MCP 호환 클라이언트와 에이전트 워크플로우를 위해 구축되었습니다.
키워드: MCP 서버, 모델 컨텍스트 프로토콜, Gemini AI, 이미지 생성, FastMCP
주요 기능:
Flash 및 Pro 티어 전반에 걸친 초고속 Gemini 이미지 생성
웹 및 게임 파이프라인을 위한 투명 PNG/WebP 에셋 출력
로컬 참조 이미지 파일을 사용한 다중 이미지 스타일 가이드
에이전트 워크플로우를 위한 유연한 파일, base64 또는 결합 출력
빠른 시작
npx를 사용하여 MCP 서버를 실행합니다:
npx -y @tasopen/mcp-alphabanana또는 MCP 구성에 추가합니다:
{
"mcp": {
"servers": {
"alphabanana": {
"command": "npx",
"args": ["-y", "@tasopen/mcp-alphabanana"],
"env": {
"GEMINI_API_KEY": "${env:GEMINI_API_KEY}"
}
}
}
}
}서버를 시작하기 전에 GEMINI_API_KEY를 설정하세요.
Claude Desktop의 경우,
mcp-alphabanana-latest.mcpb를 다운로드한 후 Claude Desktop 설정에서 확장 프로그램으로 추가합니다. Windows의 경우, 더 나은 로컬 파일 처리를 위해 'FileSystem' 확장 프로그램을 추가하는 것을 권장합니다.
Related MCP server: nano-banana-claude
Claude 레지스트리
Claude 레지스트리 / MCPB 패키지 메타데이터는 manifest.json에 정의되어 있으며 images/mcp-alphabanana.png에 있는 512x512 정적 아이콘과 함께 제공됩니다.
네이티브 sharp 런타임 패키지는 선택적 종속성으로 선언되어 있어, .mcpb 설치 시 postinstall 훅에 의존하지 않고 각 지원 플랫폼에서 올바른 사전 빌드 바이너리를 확인할 수 있습니다.
안정적인 MCPB URL:
https://github.com/tasopen/mcp-alphabanana/releases/latest/download/mcp-alphabanana-latest.mcpb버전별 MCPB URL 패턴:
https://github.com/tasopen/mcp-alphabanana/releases/download/vVERSION/mcp-alphabanana-VERSION.mcpb지원: GitHub Issues
MCP 서버
이 저장소는 AI 에이전트가 Google Gemini를 사용하여 이미지를 생성할 수 있도록 하는 MCP 서버를 제공합니다.
다음과 같은 MCP 호환 클라이언트와 함께 사용할 수 있습니다:
Claude Desktop
VS Code MCP
Cursor
간소화된 코드베이스와 유연한 출력 옵션을 위해 FastMCP 3로 구축되었습니다.
Glama MCP 서버 배지:\
사용 가능한 도구
generate_image
선택적 투명도, 로컬 참조 이미지, 그라운딩 및 추론 메타데이터를 사용하여 Google Gemini로 이미지를 생성합니다.
Claude Desktop의 경우, 중간 또는 대형 이미지에는 outputType=file을 권장합니다. base64 및 combine 응답은 Claude 컨텍스트를 소비하며 클라이언트의 크기 제한에 도달할 수 있습니다. Windows에서는 FileSystem 확장 프로그램을 사용하여 쓰기 가능한 절대 outputPath와 로컬 referenceImages 경로를 선택하세요.
주요 매개변수:
prompt(string): 생성할 이미지에 대한 설명model:Flash3.1,Flash2.5,Pro3,flash,prooutputWidth및outputHeight: 일반 모드에서 픽셀 단위의 최종 이미지 크기 요청noresize+aspectRatio+output_resolution: 크기 조정 없이 Gemini 네이티브 크기 반환output_resolution:0.5K,1K,2K,4Koutput_format:png,jpg,webpoutputType:file,base64,combineoutputPath:outputType이file또는combine일 때 필수transparent: 투명 PNG/WebP 후처리 활성화referenceImages: 로컬 참조 이미지 파일의 선택적 배열grounding_type및thinking_mode: 고급 Gemini 3.1 제어
모델 선택
입력 모델 ID | 내부 모델 ID | 설명 |
|
| 초고속, 사고/그라운딩 지원. |
|
| 레거시 Flash. 높은 안정성. 저비용. |
|
| 고충실도 Pro 모델. |
|
| 하위 호환성을 위한 별칭. |
|
| 하위 호환성을 위한 별칭. |
매개변수
generate_image 도구에 대한 전체 매개변수 참조입니다.
매개변수 | 유형 | 기본값 | 설명 |
| string | 필수 | 생성할 이미지에 대한 설명 |
| string | 필수 | 출력 파일 이름 (누락 시 확장자 자동 추가) |
| enum |
|
|
| enum |
| 모델: |
| enum | auto |
|
| boolean |
| 생성 후 크기 조정을 건너뛰고 Gemini 네이티브 치수 반환 |
| enum | 선택 사항 |
|
| integer |
| 픽셀 단위의 최종 출력 너비 |
| integer |
| 픽셀 단위의 최종 출력 높이 |
| enum |
|
|
| string |
| 절대 출력 디렉토리 경로 |
| boolean |
| 투명 배경 (PNG/WebP만 해당) |
| string 또는 null |
| 투명도 추출을 위한 색상 키 재정의 |
| integer |
| 투명도 색상 일치 허용 오차 |
| enum |
|
|
| enum |
|
|
| enum |
|
|
| enum |
|
|
| boolean |
| 메타데이터가 활성화된 경우 모델 추론 필드 반환 |
| boolean |
| JSON 출력에 그라운딩 및 추론 메타데이터 포함 |
| array |
| 최대 14개의 로컬 참조 파일 (Flash3.1/Pro3), Flash2.5는 3개 |
| boolean |
| 중간 디버그 아티팩트 저장 |
왜 alphabanana인가?
워터마크 없음: API 네이티브의 깨끗한 이미지.
사고/그라운딩 지원: 더 높은 프롬프트 준수 및 검색 기반 정확도.
프로덕션 준비 완료: 웹 및 게임 에셋을 위한 투명 WebP 및 정확한 종횡비 지원.
기능
초고속 이미지 생성 (Gemini 3.1 Flash, 0.5K/1K/2K/4K)
고급 다중 이미지 추론 (최대 14개의 참조 이미지)
사고/그라운딩 지원 (Flash3.1만 해당)
투명 PNG/WebP 출력 (색상 키 후처리, 디스필)
다양한 출력 형식: 파일, base64 또는 둘 다
유연한 크기 조정 모드: 자르기, 늘리기, 레터박스, 포함
다중 모델 티어: Flash3.1, Flash2.5, Pro3, 레거시 별칭
예시 출력
이 샘플 출력은 mcp-alphabanana로 생성되었으며 images/examples에 저장되어 있습니다.
픽셀 아트 에셋 | 참조 이미지 게임 장면 | 사실적인 생성 |
|
|
|
구성
MCP 구성(예: mcp.json)에서 GEMINI_API_KEY를 구성하세요.
예시:
mcp.json에서 OS 환경 변수 참조:
{
"env": {
"GEMINI_API_KEY": "${env:GEMINI_API_KEY}"
}
}mcp.json에 직접 키 제공:
{
"env": {
"GEMINI_API_KEY": "your_api_key_here"
}
}VS Code 통합
VS Code 설정(.vscode/settings.json 또는 사용자 설정)에 추가하고, mcp.json의 env 또는 VS Code MCP 설정을 통해 서버 env를 구성하세요.
{
"mcp": {
"servers": {
"mcp-alphabanana": {
"command": "npx",
"args": ["-y", "@tasopen/mcp-alphabanana"],
"env": {
"GEMINI_API_KEY": "${env:GEMINI_API_KEY}"
}
}
}
}
}선택 사항: env 객체에 MCP_FALLBACK_OUTPUT을 추가하여 쓰기 실패 시 사용할 사용자 지정 대체 디렉토리를 설정하세요.
사용 예시
기본 생성
{
"prompt": "A pixel art treasure chest, golden trim, wooden texture",
"model": "Flash3.1",
"outputFileName": "chest",
"outputType": "base64",
"outputWidth": 64,
"outputHeight": 64,
"transparent": true
}크기 조정 없는 네이티브 크기
{
"prompt": "A clean app icon with a banana mascot, flat graphic design",
"model": "Flash3.1",
"outputFileName": "banana-icon-native",
"outputType": "base64",
"noresize": true,
"aspectRatio": "1:1",
"output_resolution": "0.5K",
"output_format": "png"
}이 모드는 요청된 비율과 해상도에 대해 Gemini 네이티브 픽셀 크기를 반환합니다. 예를 들어, 1:1 + 0.5K는 크기 조정 과정 없이 512x512를 반환합니다.
고급 (세로 포스터 및 사고)
{
"prompt": "A vertical, photorealistic travel poster advertising Magical Wings Day Tours. A joyful young couple flies high above a breathtaking European countryside at golden hour, holding hands as they soar through a partly cloudy sky. Below them are vineyards, villages, forests, a winding river, and a hilltop medieval castle. The poster uses large, elegant typography with the headline FLY THE COUNTRYSIDE at the top and Magical Wings Day Tours branding near the bottom.",
"model": "Flash3.1",
"output_resolution": "1K",
"outputFileName": "photoreal-travel-poster",
"outputType": "file",
"outputPath": "/path/to/output",
"outputWidth": 848,
"outputHeight": 1264,
"output_format": "jpg",
"thinking_mode": "high",
"include_metadata": true
}그라운딩 샘플 (검색 기반)
{
"prompt": "A modern travel poster featuring today's weather and skyline highlights in Kuala Lumpur",
"model": "Flash3.1",
"outputFileName": "kl_travel_poster",
"outputType": "base64",
"outputWidth": 1024,
"outputHeight": 1024,
"grounding_type": "text",
"thinking_mode": "high",
"include_metadata": true,
"include_thoughts": true
}이 샘플은 Google 검색 그라운딩을 활성화하고 JSON으로 그라운딩 및 추론 메타데이터를 반환합니다.
참조 이미지 사용
{
"prompt": "Use the reference image to create a game screen showing an opened treasure chest filled with coins and treasure, 8-bit dungeon crawler style, after-battle reward scene, dungeon corridor background, four-party status UI at the bottom",
"model": "Flash3.1",
"output_resolution": "0.5K",
"outputFileName": "reference-image-dungeon-loot",
"outputType": "file",
"outputPath": "/path/to/output",
"outputWidth": 600,
"outputHeight": 448,
"output_format": "webp",
"transparent": false,
"referenceImages": [
{
"description": "Treasure chest style reference",
"filePath": "/path/to/references/pixel-art-treasure-chest.png"
}
]
}투명도 및 출력 형식
PNG: 전체 알파, 색상 키 + 디스필
WebP: 전체 알파, 더 나은 압축 (Flash3.1+)
JPEG: 투명도 없음 (단색 배경으로 대체)
개발
# Development mode with MCP CLI
npm run dev
# MCP Inspector (Web UI)
npm run inspect
# Build for production
npm run build라이선스
MIT
Available Tools
1 toolgenerate_imageADestructive
Generate image assets using Gemini AI with optional transparency and reference images.
[Claude Desktop Guidance]
Prefer outputType='file' for medium or large images. base64 and combine responses can exceed Claude Desktop's context limit.
On Claude Desktop for Windows, use the FileSystem extension to choose reference-image paths and a writable absolute outputPath before calling this tool.
Use base64 only for small previews or when the client explicitly needs inline image data.
[Model Guidance]
Flash3.1 (recommended): High quality, very fast, supports grounding and advanced features.
Lite3.1 (Nano Banana 2 Lite): Ultra-fast, cost-effective, 1K-only, no search grounding. Ideal for quick drafting and low-latency iteration.
Pro3: Higher fidelity, but more costly and slower.
Flash2.5: Legacy, maintained for compatibility. Does not support 0.5K, 2K, or 4K resolutions.
[Aspect Ratios] Gemini supports the following aspect ratios (model-dependent):
Common to all models: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
Flash3.1 only: 1:4, 4:1, 1:8, 8:1
Normal mode: provide outputWidth/outputHeight and the server will choose the closest Gemini aspect ratio and source resolution, then resize to the requested pixel size. No-resize mode: set noresize=true and provide aspectRatio plus output_resolution. The server will return Gemini's native pixel dimensions for that combination without post-generation resizing.
If you intentionally want to control resizing/cropping in normal mode, use the 'resizeMode' parameter: 'crop' (default, center crop), 'letterbox' (fit with padding), 'contain' (trim transparent margins then fit), or 'stretch' (distort to fit).
[IMPORTANT] Always preserve the user's prompt as-is, including language and nuance. Do not translate or summarize.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| debug | No | Debug mode: output intermediate processing images and prompt | |
| model | No | Model tier to use for generation (see tool description for details; "flash" and "pro" are aliases for Flash2.5 and Pro3; "Lite3.1" is the low-latency Nano Banana 2 Lite model, 1K-only, no grounding) | Flash3.1 |
| prompt | Yes | User-provided image prompt. Preserve the original wording and detail; do not summarize or translate. Only append transparency-related hints if needed. | |
| noresize | No | Skip post-generation resizing and return Gemini native dimensions directly. When true, provide aspectRatio and output_resolution instead of outputWidth/outputHeight. | |
| fringeMode | No | Fringe reduction mode: auto (size-based), crisp (binary alpha), hd (force-clear 1px boundary for large images). | auto |
| outputPath | No | Output directory path (MUST be an absolute path when outputType is file or combine). In Claude Desktop on Windows, use the FileSystem extension to choose or prepare a writable absolute path such as C:\temp. | |
| outputType | No | Output format: file=file only, base64=base64 only, combine=both. In Claude Desktop, prefer file for medium or large images to avoid context-size limits; use base64 only for small previews. | combine |
| resizeMode | No | Resize mode: crop=center crop, stretch=distort, letterbox=fit with padding, contain=trim transparent margins then fit | crop |
| aspectRatio | No | Gemini aspect ratio to use directly when noresize=true. Ignored in normal resize mode. | |
| outputWidth | No | Output image width in pixels. Required unless noresize=true. In normal mode, the image will be generated using the closest supported Gemini aspect ratio and resolution, then resized to this width. | |
| transparent | No | Request transparent background (PNG or WebP only). Background color is selected by histogram analysis. | |
| outputHeight | No | Output image height in pixels. Required unless noresize=true. In normal mode, the image will be generated using the closest supported Gemini aspect ratio and resolution, then resized to this height. | |
| output_format | No | Output format | png |
| thinking_mode | No | Thinking mode (3.1 only) | minimal |
| colorTolerance | No | Tolerance for color matching (0-255). Higher values are more permissive for transparent color selection and keying. | |
| grounding_type | No | Grounding tool usage (3.1 only) | none |
| outputFileName | Yes | Output filename (extension auto-added if missing) | |
| referenceImages | No | Reference images for style guidance (Flash2.5: max 3, others: max 14) | |
| include_metadata | No | Include grounding and reasoning metadata in JSON output (optional, may increase payload size). | |
| include_thoughts | No | Optional (default: false). Request thought fields from Gemini (3.1 only). Thought content is returned in MCP response only when include_metadata=true. | |
| transparentColor | No | Color to make transparent. Hex (e.g. #FF00FF). null defaults to #FF00FF when transparent=true. | |
| output_resolution | No | Gemini generation source resolution (optional in normal mode, required when noresize=true). In normal mode, the final image is resized to the requested pixel size after generation. |
TDQS
A4.5/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behaviors beyond annotations: it explains that the tool generates files on disk (outputPath), handles resizing and cropping, supports transparency, and has model-dependent features. Annotations already indicate destructiveHint=true and openWorldHint=true, so the description adds context about what gets created and modified. However, it does not explicitly warn about overwriting existing files, which would have earned a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but well-structured with sections (Claude Desktop Guidance, Model Guidance, Aspect Ratios, IMPORTANT) and uses bullet points for readability. It front-loads the main purpose and then provides detailed guidance. While every sentence contributes value, some redundancy with schema descriptions could be trimmed slightly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (22 parameters, multiple modes, platform specifics), the description is quite comprehensive. It covers purpose, usage guidelines, model comparisons, resize behavior, output types, and important notes. However, it lacks explicit details about error responses or rate limits, and there is no output schema, but the description compensates well for the tool's generative nature.
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?
Schema coverage is 100%, so parameters are already documented. The description adds value by grouping parameters logically (e.g., model selection, aspect ratios, resize modes) and providing context for platform-specific usage (e.g., referenceImages filePath on Windows). It explains the interaction between parameters like outputWidth/outputHeight and noresize, which goes beyond individual parameter descriptions.
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 image assets using Gemini AI with optional transparency and reference images,' clearly stating the action, resource, and technology. It differentiates between different usage contexts (Claude Desktop, Windows, etc.) and provides model recommendations, ensuring the agent understands what the tool does and when to use which option.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines5/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes explicit guidance on when to use different output types ('Prefer outputType='file' for medium or large images'), when to use noresize mode vs normal mode, and when to choose each model (Flash3.1 recommended, Lite3.1 for quick drafting, etc.). It also provides platform-specific usage instructions for Claude Desktop and Windows, giving clear context for tool selection.
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 tool update
v1.5.0- Changed
generate_image14 fields changed- added
Input schema / properties / aspectRatioAdded value: +{ + "description": "Gemini aspect ratio to use directly when noresize=true. Ignored in normal resize mode.", + "enum": [ + "1:1", + "2:3", + "3:2", + "3:4", + "4:3", + "4:5", + "5:4", + "9:16", + "16:9", + "21:9", + "1:4", + "4:1", + "1:8", + "8:1" + ], + "type": "string" +} - changed
Input schema / properties / model / descriptionPrevious value: -"Model tier to use for generation (see tool description for details; \"flash\" and \"pro\" are aliases for Flash2.5 and Pro3)"New value: +"Model tier to use for generation (see tool description for details; \"flash\" and \"pro\" are aliases for Flash2.5 and Pro3; \"Lite3.1\" is the low-latency Nano Banana 2 Lite model, 1K-only, no grounding)" - changed
Input schema / properties / model / enumPrevious value: -[ - "Flash3.1", - "Flash2.5", - "Pro3", - "flash", - "pro" -]New value: +[ + "Flash3.1", + "Lite3.1", + "Flash2.5", + "Pro3", + "flash", + "pro" +] - added
Input schema / properties / noresizeAdded value: +{ + "default": false, + "description": "Skip post-generation resizing and return Gemini native dimensions directly. When true, provide aspectRatio and output_resolution instead of outputWidth/outputHeight.", + "type": "boolean" +} - changed
Input schema / properties / outputHeight / descriptionPrevious value: -"Output image height in pixels. The image will be generated using the closest supported Gemini aspect ratio and resolution, then resized to this height. To avoid cropping or padding, set width and height to match a supported aspect ratio (see tool description)."New value: +"Output image height in pixels. Required unless noresize=true. In normal mode, the image will be generated using the closest supported Gemini aspect ratio and resolution, then resized to this height." - changed
Input schema / properties / outputPath / descriptionPrevious value: -"Output directory path (MUST be an absolute path when outputType is file or combine)"New value: +"Output directory path (MUST be an absolute path when outputType is file or combine). In Claude Desktop on Windows, use the FileSystem extension to choose or prepare a writable absolute path such as C:\\temp." - changed
Input schema / properties / outputType / descriptionPrevious value: -"Output format: file=file only, base64=base64 only, combine=both"New value: +"Output format: file=file only, base64=base64 only, combine=both. In Claude Desktop, prefer file for medium or large images to avoid context-size limits; use base64 only for small previews." - changed
Input schema / properties / outputWidth / descriptionPrevious value: -"Output image width in pixels. The image will be generated using the closest supported Gemini aspect ratio and resolution, then resized to this width. To avoid cropping or padding, set width and height to match a supported aspect ratio (see tool description)."New value: +"Output image width in pixels. Required unless noresize=true. In normal mode, the image will be generated using the closest supported Gemini aspect ratio and resolution, then resized to this width." - changed
Input schema / properties / output_resolution / descriptionPrevious value: -"Gemini generation source resolution (optional; normally auto-calculated from pixel size. Set only to override. Final image is resized to requested pixel size.)"New value: +"Gemini generation source resolution (optional in normal mode, required when noresize=true). In normal mode, the final image is resized to the requested pixel size after generation." - removed
Input schema / properties / referenceImages / items / additionalPropertiesRemoved value: -false - changed
Input schema / properties / referenceImages / items / properties / filePath / descriptionPrevious value: -"Absolute path to reference image file (.png, .jpg, .jpeg, .webp)"New value: +"Absolute path to reference image file (.png, .jpg, .jpeg, .webp). In Claude Desktop on Windows, use the FileSystem extension to locate the file and pass its Windows absolute path." - added
Input schema / properties / transparentColor / anyOfAdded value: +[ + { + "type": "string" + }, + { + "type": "null" + } +] - removed
Input schema / properties / transparentColor / typeRemoved value: -[ - "string", - "null" -] - changed
Input schema / requiredPrevious value: -[ - "prompt", - "outputFileName", - "outputWidth", - "outputHeight" -]New value: +[ + "prompt", + "outputFileName" +]
1 tool update
v1.3.6- First observed
generate_image
TDQS
A4.6/5.0
Scored across 1 tool
Disambiguation5/5
With only one tool, there is no potential for confusion between tools. The single tool's purpose is clearly defined as generating images.
Naming Consistency5/5
There is only one tool, so naming consistency is not applicable. The tool name 'generate_image' follows a clear verb_noun convention.
Tool Count4/5
The server has a single tool, which is slightly thin but acceptable given the tool's complexity and the server's focused purpose of image generation. The tool includes many parameters and guidance, making it substantial.
Completeness5/5
The tool provides comprehensive image generation capabilities with support for multiple AI models, aspect ratios, output formats, and advanced options like no-resize and resize modes. It covers the full scope of image generation for the server's domain.
Maintenance
ActivityStale
ResponsivenessUnresponsive
Related MCP Connectors
MCP server for Qwen Image 3 AI image generation
MCP server for NanoBanana AI image generation and editing
Focused MCP server for OpenAI image/audio generation (v2.0.0). Wraps endpoints via HAPI CLI.
MCP server for Google Veo AI video generation
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that provides image generation using Google's Nano Banana Gemini models, with additional tools for background removal, upscaling, and format conversion via deterministic post-processing.1MIT
- FlicenseAqualityDmaintenanceWraps Google Gemini's image generation API as an MCP server, enabling text-to-image, image editing, and grounded search workflows from any MCP client.2-
- AlicenseNot gradedqualityDmaintenanceMCP server for Google's Nano Banana image generation models (Gemini). Generate and edit images via natural language.8 npm1MIT