mcp-alphabanana

English | 日本語

A Model Context Protocol (MCP) server for generating image assets using Google Gemini AI (Gemini 3.1 Flash/Nano Banana 2 supported).

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

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/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

Installation

Add @tasopen/mcp-alphabanana to your MCP Servers configuration.

Configuration

Configure the GEMINI_API_KEY in your MCP configuration (e.g. 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}"  // or "your_api_key_here"
        }
      }
    }
  }
}

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

Model Selection & Parameters

Parameters (v2.0)

Usage Examples

Basic Generation

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

Advanced (WebP, thinking, grounding)

{
  "prompt": "A photorealistic girl with wings flying over a European countryside",
  "model": "Flash3.1",
  "outputFileName": "girl_wings",
  "outputWidth": 632,
  "outputHeight": 424,
  "output_format": "webp",
  "thinking_mode": "high",
  "grounding_type": "both",
  "include_thoughts": 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",
  "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/reasoning metadata in JSON.

With Reference Images

{
  "prompt": "A matching treasure chest, open state, same pixel art style as references",
  "model": "Pro3",
  "outputFileName": "chest_open",
  "outputWidth": 64,
  "outputHeight": 64,
  "transparent": true,
  "reference_images": [
    {
      "description": "Closed chest for style reference",
      "data": "...base64..."
    }
  ]
}

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