Skip to main content
Glama
deenesjakoruzh
tasopen

mcp-alphabanana

by tasopen
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript

mcp-alphabanana

npm version License: MIT

English | 日本語

mcp-alphabananaは、Google Geminiを使用して画像アセットを生成するためのModel Context Protocol (MCP) サーバーです。高速な画像生成、透過出力、参照画像によるガイダンス、柔軟な配信フォーマットを必要とするMCP互換クライアントおよびエージェントワークフロー向けに構築されています。

キーワード: MCPサーバー, Model Context Protocol, Gemini AI, 画像生成, FastMCP

主な機能:

  • FlashおよびProティア全体での超高速Gemini画像生成

  • Webおよびゲームパイプライン向けの透過PNG/WebPアセット出力

  • ローカルの参照画像ファイルを使用したマルチ画像スタイルガイダンス

  • エージェントワークフロー向けの柔軟なファイル、base64、または結合出力

alphabanana demo

クイックスタート

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」拡張機能を追加することを推奨します。 Download MCPB

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 Serverバッジ:

利用可能なツール

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制御

モデル選択

入力モデルID

内部モデルID

説明

Flash3.1

gemini-3.1-flash-image-preview

超高速、Thinking/Groundingをサポート。

Flash2.5

gemini-2.5-flash-image

レガシーFlash。高い安定性。低コスト。

Pro3

gemini-3.0-pro-image-preview

高忠実度Proモデル。

flash

gemini-3.1-flash-image-preview

下位互換性のためのエイリアス。

pro

gemini-3.0-pro-image-preview

下位互換性のためのエイリアス。

パラメータ

generate_image ツールの全パラメータリファレンス。

パラメータ

型

デフォルト

説明

prompt

string

必須

生成する画像の記述

outputFileName

string

必須

出力ファイル名（拡張子がない場合は自動追加）

outputType

enum

combine

file, base64, または combine

model

enum

Flash3.1

モデル: Flash3.1, Flash2.5, Pro3, flash, pro

output_resolution

enum

auto

0.5K, 1K, 2K, 4K; noresize=true の場合に必須

noresize

boolean

false

生成後のリサイズをスキップし、Geminiネイティブの寸法を返す

aspectRatio

enum

オプション

noresize=true の場合に必須; 例: 1:1, 16:9, 4:5

outputWidth

integer

noresize=true 以外は必須

最終出力の幅（ピクセル単位）

outputHeight

integer

noresize=true 以外は必須

最終出力の高さ（ピクセル単位）

output_format

enum

png

png, jpg, webp

outputPath

string

file / combine で必須

絶対出力ディレクトリパス

transparent

boolean

false

透過背景（PNG/WebPのみ）

transparentColor

string or null

null

透過抽出用のカラーキーオーバーライド

colorTolerance

integer

30

透過色マッチングの許容値

fringeMode

enum

auto

auto, crisp, hd

resizeMode

enum

crop

crop, stretch, letterbox, contain

grounding_type

enum

none

none, text, image, both (Flash3.1のみ)

thinking_mode

enum

minimal

minimal, high (Flash3.1のみ)

include_thoughts

boolean

false

メタデータが有効な場合にモデルの推論フィールドを返す

include_metadata

boolean

false

JSON出力にグラウンディングと推論のメタデータを含める

referenceImages

array

[]

最大14個のローカル参照ファイル (Flash3.1/Pro3)、Flash2.5は3個

debug

boolean

false

中間デバッグアーティファクトを保存

なぜalphabananaなのか？

  • 透かしなし: APIネイティブのクリーンな画像。

  • Thinking/Groundingサポート: より高いプロンプト順守と検索に裏打ちされた正確性。

  • 本番環境対応: Webおよびゲームアセット向けの透過WebPと正確なアスペクト比をサポート。

機能

  • 超高速画像生成 (Gemini 3.1 Flash, 0.5K/1K/2K/4K)

  • 高度なマルチ画像推論 (最大14枚の参照画像)

  • Thinking/Groundingサポート (Flash3.1のみ)

  • 透過PNG/WebP出力 (カラーキーポストプロセッシング、デスピル)

  • 複数の出力フォーマット: ファイル、base64、または両方

  • 柔軟なリサイズモード: クロッピング、ストレッチ、レターボックス、コンテイン

  • 複数のモデルティア: Flash3.1, Flash2.5, Pro3, レガシーエイリアス

出力例

これらのサンプル出力はmcp-alphabananaで生成され、images/examples に保存されています。

ピクセルアートアセット

参照画像ゲームシーン

フォトリアルな生成

Pixel art treasure chest

Reference-image dungeon loot scene

Photorealistic travel poster

設定

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 tool
generate_imageA
Destructive

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
NameRequiredDescriptionDefault
debugNoDebug mode: output intermediate processing images and prompt
modelNoModel 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
promptYesUser-provided image prompt. Preserve the original wording and detail; do not summarize or translate. Only append transparency-related hints if needed.
noresizeNoSkip post-generation resizing and return Gemini native dimensions directly. When true, provide aspectRatio and output_resolution instead of outputWidth/outputHeight.
fringeModeNoFringe reduction mode: auto (size-based), crisp (binary alpha), hd (force-clear 1px boundary for large images).auto
outputPathNoOutput 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.
outputTypeNoOutput 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
resizeModeNoResize mode: crop=center crop, stretch=distort, letterbox=fit with padding, contain=trim transparent margins then fitcrop
aspectRatioNoGemini aspect ratio to use directly when noresize=true. Ignored in normal resize mode.
outputWidthNoOutput 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.
transparentNoRequest transparent background (PNG or WebP only). Background color is selected by histogram analysis.
outputHeightNoOutput 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_formatNoOutput formatpng
thinking_modeNoThinking mode (3.1 only)minimal
colorToleranceNoTolerance for color matching (0-255). Higher values are more permissive for transparent color selection and keying.
grounding_typeNoGrounding tool usage (3.1 only)none
outputFileNameYesOutput filename (extension auto-added if missing)
referenceImagesNoReference images for style guidance (Flash2.5: max 3, others: max 14)
include_metadataNoInclude grounding and reasoning metadata in JSON output (optional, may increase payload size).
include_thoughtsNoOptional (default: false). Request thought fields from Gemini (3.1 only). Thought content is returned in MCP response only when include_metadata=true.
transparentColorNoColor to make transparent. Hex (e.g. #FF00FF). null defaults to #FF00FF when transparent=true.
output_resolutionNoGemini 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. 1 tool updatev1.5.0
    • Changedgenerate_image14 fields changed
      • addedInput schema / properties / aspectRatio
        Added 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"
+}
      • changedInput schema / properties / model / description
        Previous 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)"
      • changedInput schema / properties / model / enum
        Previous value: -[
-  "Flash3.1",
-  "Flash2.5",
-  "Pro3",
-  "flash",
-  "pro"
-]New value: +[
+  "Flash3.1",
+  "Lite3.1",
+  "Flash2.5",
+  "Pro3",
+  "flash",
+  "pro"
+]
      • addedInput schema / properties / noresize
        Added 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"
+}
      • changedInput schema / properties / outputHeight / description
        Previous 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."
      • changedInput schema / properties / outputPath / description
        Previous 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."
      • changedInput schema / properties / outputType / description
        Previous 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."
      • changedInput schema / properties / outputWidth / description
        Previous 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."
      • changedInput schema / properties / output_resolution / description
        Previous 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."
      • removedInput schema / properties / referenceImages / items / additionalProperties
        Removed value: -false
      • changedInput schema / properties / referenceImages / items / properties / filePath / description
        Previous 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."
      • addedInput schema / properties / transparentColor / anyOf
        Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
      • removedInput schema / properties / transparentColor / type
        Removed value: -[
-  "string",
-  "null"
-]
      • changedInput schema / required
        Previous value: -[
-  "prompt",
-  "outputFileName",
-  "outputWidth",
-  "outputHeight"
-]New value: +[
+  "prompt",
+  "outputFileName"
+]
  2. 1 tool updatev1.3.6
    • First observedgenerate_image
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

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

Resources

Related MCP Connectors

Related MCP Servers