convez.ai
MCP ServerDesign & UIIntermediário
tasopen

mcp-alphabanana

tasopen/mcp-alphabanana

Geração rápida de imagens com Gemini para workflows de IA

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP para gerar imagens com Google Gemini AI, oferecendo saídas transparentes em PNG/WebP, redimensionamento flexível e suporte a imagens de referência locais. Integra-se nativamente com clientes MCP como Claude Desktop e Cursor.

Instalação

$npx convez-ai tasopen/mcp-alphabanana

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
10
Forks
3
Acompanhando
0
Saúde
42%
Último commit
há 1 mês
Versão
v1.6.0
Issues abertas
1
Contribuidores
1

Casos de uso

  • Gerar assets visuais em tempo real para aplicações web
  • Criar imagens de referência para pipelines de design e games
  • Automatizar produção de imagens com transparência para UI/UX
  • Integrar geração de imagens em agentes Claude

Veredito

MCP server robusto e bem mantido para geração de imagens via Gemini. Ideal para equipes que precisam automatizar criação de assets visuais em pipelines de desenvolvimento. Documentação clara e suporte multiplataforma (Windows, Linux, macOS) através de MCPB.

README

A tradução para o português deste README ainda está na fila.

mcp-alphabanana

npm version License: MIT

English | 日本語

mcp-alphabanana is a Model Context Protocol (MCP) server for generating image assets with Google Gemini. It is built for MCP-compatible clients and agent workflows that need fast image generation, transparent outputs, reference-image guidance, and flexible delivery formats.

Keywords: MCP server, Model Context Protocol, Gemini AI, image generation, FastMCP

Key capabilities:

  • Ultra-fast Gemini image generation across Flash and Pro tiers
  • Transparent PNG/WebP asset output for web and game pipelines
  • Multi-image style guidance with local reference image files
  • Flexible file, base64, or combined outputs for agent workflows

alphabanana demo

Quick Start

Run the MCP server with npx:

npx -y @tasopen/mcp-alphabanana

Or add it to your MCP configuration:

{
  "mcp": {
    "servers": {
      "alphabanana": {
        "command": "npx",
        "args": ["-y", "@tasopen/mcp-alphabanana"],
        "env": {
          "GEMINI_API_KEY": "${env:GEMINI_API_KEY}"
        }
      }
    }
  }
}

Set GEMINI_API_KEY before starting the server.

For Claude Desktop, Download mcp-alphabanana-latest.mcpb, then add it as Extension from Claude Desktop Settings. For Windows, Recommend add 'FileSystem' extension for better local file handling.
Download MCPB

Claude Registry

The Claude registry / MCPB package metadata is defined in manifest.json and ships with the static 512x512 icon at images/mcp-alphabanana.png.

Native sharp runtime packages are declared as optional dependencies so .mcpb installs can resolve the correct prebuilt binary on each supported platform without relying on postinstall hooks.

  • Stable MCPB URL: https://github.com/tasopen/mcp-alphabanana/releases/latest/download/mcp-alphabanana-latest.mcpb
  • Versioned MCPB URL pattern: https://github.com/tasopen/mcp-alphabanana/releases/download/vVERSION/mcp-alphabanana-VERSION.mcpb
  • Support: GitHub Issues

MCP Server

This repository provides an MCP server that enables AI agents to generate images using Google Gemini.

It can be used with MCP-compatible clients such as:

  • Claude Desktop
  • VS Code MCP
  • Cursor

Built with FastMCP 3 for a simplified codebase and flexible output options.

Glama MCP Server badge:

Available Tools

generate_image

Generates images using Google Gemini with optional transparency, local reference images, grounding, and reasoning metadata.

For Claude Desktop, prefer outputType=file for medium or large images. base64 and combine responses consume Claude context and can hit the client's size limit. On Windows, use the FileSystem extension to choose a writable absolute outputPath and any local referenceImages paths.

Key parameters:

  • prompt (string): description of the image to generate
  • model: Flash3.1, Flash2.5, Pro3, flash, pro
  • outputWidth and outputHeight: requested final image size in pixels in normal mode
  • noresize + aspectRatio + output_resolution: return Gemini native size without resizing
  • output_resolution: 0.5K, 1K, 2K, 4K
  • output_format: png, jpg, webp
  • outputType: file, base64, combine
  • outputPath: required when outputType is file or combine
  • transparent: enable transparent PNG/WebP post-processing
  • referenceImages: optional array of local reference image files
  • grounding_type and thinking_mode: advanced Gemini 3.1 controls

Model Selection

Input Model IDInternal Model IDDescription
Flash3.1gemini-3.1-flash-image-previewUltra-fast, supports Thinking/Grounding.
Flash2.5gemini-2.5-flash-imageLegacy Flash. High stability. Low cost.
Pro3gemini-3.0-pro-image-previewHigh-fidelity Pro model.
flashgemini-3.1-flash-image-previewAlias for backward compatibility.
progemini-3.0-pro-image-previewAlias for backward compatibility.

Parameters

Full parameter reference for the generate_image tool.

ParameterTypeDefaultDescription
promptstringrequiredDescription of the image to generate
outputFileNamestringrequiredOutput filename (extension auto-added if missing)
outputTypeenumcombinefile, base64, or combine
modelenumFlash3.1Model: Flash3.1, Flash2.5, Pro3, flash, pro
output_resolutionenumauto0.5K, 1K, 2K, 4K; required when noresize=true
noresizebooleanfalseSkip post-generation resize and return Gemini native dimensions
aspectRatioenumoptionalRequired when noresize=true; e.g. 1:1, 16:9, 4:5
outputWidthintegerrequired unless noresize=trueFinal output width in pixels
outputHeightintegerrequired unless noresize=trueFinal output height in pixels
output_formatenumpngpng, jpg, webp
outputPathstringrequired for file / combineAbsolute output directory path
transparentbooleanfalseTransparent background (PNG/WebP only)
transparentColorstring or nullnullColor key override for transparency extraction
colorToleranceinteger30Transparency color matching tolerance
fringeModeenumautoauto, crisp, hd
resizeModeenumcropcrop, stretch, letterbox, contain
grounding_typeenumnonenone, text, image, both (Flash3.1 only)
thinking_modeenumminimalminimal, high (Flash3.1 only)
include_thoughtsbooleanfalseReturn model reasoning fields when metadata is enabled
include_metadatabooleanfalseInclude grounding and reasoning metadata in JSON output
referenceImagesarray[]Up to 14 local reference files (Flash3.1/Pro3), 3 for Flash2.5
debugbooleanfalseSave intermediate debug artifacts

Why alphabanana?

  • Zero Watermarks: API-native clean images.
  • Thinking/Grounding Support: Higher prompt adherence and search-backed accuracy.
  • Production Ready: Supports transparent WebP and exact aspect ratios for web and game assets.

Features

  • Ultra-fast image generation (Gemini 3.1 Flash, 0.5K/1K/2K/4K)
  • Advanced multi-image reasoning (up to 14 reference images)
  • Thinking/Grounding support (Flash3.1 only)
  • Transparent PNG/WebP output (color-key post-processing, despill)
  • Multiple output formats: file, base64, or both
  • Flexible resize modes: crop, stretch, letterbox, contain
  • Multiple model tiers: Flash3.1, Flash2.5, Pro3, legacy aliases

Example Outputs

These sample outputs were generated with mcp-alphabanana and stored in images/examples.

Pixel art assetReference-image game scenePhotorealistic generation
Pixel art treasure chestReference-image dungeon loot scenePhotorealistic travel poster

Configuration

Configure the GEMINI_API_KEY in your MCP configuration (for example, mcp.json).

Examples:

  • Reference an OS environment variable from mcp.json:
{
  "env": {
    "GEMINI_API_KEY": "${env:GEMINI_API_KEY}"
  }
}
  • Provide the key directly in mcp.json:
{
  "env": {
    "GEMINI_API_KEY": "your_api_key_here"
  }
}

VS Code Integration

Add to your VS Code settings (.vscode/settings.json or user settings), configuring the server env in mcp.json or via the VS Code MCP settings.

{
  "mcp": {
    "servers": {
      "mcp-alphabanana": {
        "command": "npx",
        "args": ["-y", "@tasopen/mcp-alphabanana"],
        "env": {
          "GEMINI_API_KEY": "${env:GEMINI_API_KEY}"
        }
      }
    }
  }
}

Optional: Set a custom fallback directory for write failures by adding MCP_FALLBACK_OUTPUT to the env object.

Usage Examples

Basic Generation

{
  "prompt": "A pixel art treasure chest, golden trim, wooden texture",
  "model": "Flash3.1",
  "outputFileName": "chest",
  "outputType": "base64",
  "outputWidth": 64,
  "outputHeight": 64,
  "transparent": true
}

Native Size Without Resize

{
  "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"
}

This mode returns the Gemini native pixel size for the requested ratio and resolution. For example, 1:1 + 0.5K returns 512x512 without any resize pass.

Advanced (Vertical poster and thinking)

{
  "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
}

Grounding Sample (Search-backed)

{
  "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
}

This sample enables Google Search grounding and returns grounding and reasoning metadata in JSON.

With Reference Images

{
  "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"
    }
  ]
}

Transparency & Output Formats

  • PNG: Full alpha, color-key + despill
  • WebP: Full alpha, better compression (Flash3.1+)
  • JPEG: No transparency (falls back to solid background)

Development

# Development mode with MCP CLI
npm run dev

# MCP Inspector (Web UI)
npm run inspect

# Build for production
npm run build

License

MIT

Ver o original no GitHub

Bom para

Relacionados