mcp-alphabanana

English | 日本語

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

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

主な機能:

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

• Webおよびゲームパイプライン向けの透過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 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制御

モデル選択

パラメータ

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

なぜ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 に保存されています。

設定

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