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' 확장 프로그램을 추가하는 것을 권장합니다.

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, pro

• outputWidth 및 outputHeight: 일반 모드에서 픽셀 단위의 최종 이미지 크기 요청

• noresize + aspectRatio + output_resolution: 크기 조정 없이 Gemini 네이티브 크기 반환

• output_resolution: 0.5K, 1K, 2K, 4K

• output_format: png, jpg, webp

• outputType: file, base64, combine

• outputPath: outputType이 file 또는 combine일 때 필수

• transparent: 투명 PNG/WebP 후처리 활성화

• referenceImages: 로컬 참조 이미지 파일의 선택적 배열

• grounding_type 및 thinking_mode: 고급 Gemini 3.1 제어

모델 선택

매개변수

generate_image 도구에 대한 전체 매개변수 참조입니다.

왜 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