# mcp-alphabanana
[](https://www.npmjs.com/package/@tasopen/mcp-alphabanana)
[](LICENSE)
English | [日本語](README.ja.md)
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:
- Nano Banana 2.1 image generation by default, plus Lite, 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
## Quick Start
Run the MCP server with npx:
```bash
npx -y @tasopen/mcp-alphabanana
```
Or add it to your MCP configuration:
```json
{
"mcp": {
"servers": {
"mcp-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.
[](https://github.com/tasopen/mcp-alphabanana/releases/latest/download/mcp-alphabanana-latest.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](https://github.com/tasopen/mcp-alphabanana/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](https://www.npmjs.com/package/fastmcp) 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`: `NanoBanana2.1` (default), `Flash3.1` (deprecated), `Lite3.1`, `Flash2.5`, `Pro3`, plus aliases `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`: `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 controls (`thinking_mode`: `minimal` / `medium` / `high`, default `medium`)
### Model Selection
| Input Model ID | Internal Model ID | Description |
| --- | --- | --- |
| `NanoBanana2.1` | `gemini-nano-banana-2.1` | **Default.** Google Nano Banana 2.1. Best overall quality, prompt adherence, text rendering, and reference-image handling. 1K/2K/4K, up to 14 reference images. |
| `Flash3.1` | `gemini-3.1-flash-image` | **Deprecated.** Ultra-fast, supports Thinking/Grounding. Google shuts it down on October 29, 2026; requests are rejected from that date. Migrate to `NanoBanana2.1`. |
| `Lite3.1` | `gemini-3.1-flash-lite-image` | Ultra-fast, cost-effective 1K-only model. No Search Grounding. |
| `Flash2.5` | `gemini-2.5-flash-image` | Legacy Flash. High stability. Low cost. 1K only. |
| `Pro3` | `gemini-3-pro-image` | High-fidelity Pro model. |
| `flash` | `gemini-nano-banana-2.1` | Alias for the default model (`NanoBanana2.1`). |
| `pro` | `gemini-3-pro-image` | Alias for `Pro3`. |
### Parameters
Full parameter reference for the `generate_image` tool.
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `prompt` | string | *required* | Description of the image to generate |
| `outputFileName` | string | *required* | Output filename (extension auto-added if missing) |
| `outputType` | enum | `combine` | `file`, `base64`, or `combine` |
| `model` | enum | `NanoBanana2.1` | Model: `NanoBanana2.1`, `Flash3.1`, `Lite3.1`, `Flash2.5`, `Pro3`, `flash`, `pro` |
| `output_resolution` | string | auto | `1K`, `2K`, `4K` (`0.5K` removed in v1.6.0); required when `noresize=true` |
| `noresize` | boolean | `false` | Skip post-generation resize and return Gemini native dimensions |
| `aspectRatio` | enum | optional | Required when `noresize=true`; e.g. `1:1`, `16:9`, `4:5` |
| `outputWidth` | integer | required unless `noresize=true` | Final output width in pixels |
| `outputHeight` | integer | required unless `noresize=true` | Final output height in pixels |
| `output_format` | enum | `png` | `png`, `jpg`, `webp` |
| `outputPath` | string | required for `file` / `combine` | Absolute output directory path |
| `transparent` | boolean | `false` | Transparent background (PNG/WebP only) |
| `transparentColor` | string or null | `null` | Color key override for transparency extraction |
| `colorTolerance` | integer | `30` | Transparency color matching tolerance |
| `fringeMode` | enum | `auto` | `auto`, `crisp`, `hd` |
| `resizeMode` | enum | `crop` | `crop`, `stretch`, `letterbox`, `contain` |
| `grounding_type` | enum | `none` | `none`, `text`, `image`, `both` (grounding-capable models: `NanoBanana2.1`, `Flash3.1`, `Pro3`) |
| `thinking_mode` | enum | `medium` | `minimal`, `medium`, `high` (thinking-capable models: `NanoBanana2.1` accepts all three; `Flash3.1`/`Pro3` accept `minimal`/`high` and fall back to their own default otherwise) |
| `include_thoughts` | boolean | `false` | Return model reasoning fields when metadata is enabled |
| `include_metadata` | boolean | `false` | Include grounding and reasoning metadata in JSON output |
| `referenceImages` | array | `[]` | Up to 14 local reference files (`NanoBanana2.1`/`Flash3.1`/`Pro3`/`Lite3.1`), 3 for `Flash2.5` |
| `debug` | boolean | `false` | Save 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
- **Nano Banana 2.1 default** (`gemini-nano-banana-2.1`, 1K/2K/4K output)
- **Nano Banana 2 Lite** (`Lite3.1`): ultra-fast, cost-effective 1K-only model for quick drafting and low-latency iteration
- **Advanced multi-image reasoning** (up to 14 reference images)
- **Thinking/Grounding support** (`NanoBanana2.1`, `Flash3.1`, `Pro3`)
- **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**: NanoBanana2.1 (default), Flash3.1 (deprecated), Lite3.1, Flash2.5, Pro3, legacy aliases
## Example Outputs
These sample outputs were generated with mcp-alphabanana and stored in [images/examples](images/examples).
| Pixel art asset | Reference-image game scene | Photorealistic generation |
| --- | --- | --- |
|  |  |  |
## Configuration
Configure the `GEMINI_API_KEY` in your MCP configuration (for example, `mcp.json`).
Examples:
- Reference an OS environment variable from `mcp.json`:
```json
{
"env": {
"GEMINI_API_KEY": "${env:GEMINI_API_KEY}"
}
}
```
- Provide the key directly in `mcp.json`:
```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.
```json
{
"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
```json
{
"prompt": "A pixel art treasure chest, golden trim, wooden texture",
"model": "NanoBanana2.1",
"outputFileName": "chest",
"outputType": "base64",
"outputWidth": 64,
"outputHeight": 64,
"transparent": true
}
```
#### Native Size Without Resize
```json
{
"prompt": "A clean app icon with a banana mascot, flat graphic design",
"model": "NanoBanana2.1",
"outputFileName": "banana-icon-native",
"outputType": "base64",
"noresize": true,
"aspectRatio": "1:1",
"output_resolution": "1K",
"output_format": "png"
}
```
This mode returns the Gemini native pixel size for the requested ratio and resolution. For example, `1:1` + `1K` returns `1024x1024` without any resize pass. (`0.5K` was removed in v1.6.0.)
#### Advanced (Vertical poster and thinking)
```json
{
"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": "NanoBanana2.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)
```json
{
"prompt": "A modern travel poster featuring today's weather and skyline highlights in Kuala Lumpur",
"model": "NanoBanana2.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
```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": "NanoBanana2.1",
"output_resolution": "1K",
"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
- **JPEG**: No transparency (falls back to solid background)
> Nano Banana 2.1 does not provide native transparent output. When `transparent=true` is specified, mcp-alphabanana applies local post-processing to generate an alpha channel.
## Development
```bash
# Development mode with MCP CLI
npm run dev
# MCP Inspector (Web UI)
npm run inspect
# Build for production
npm run build
```
## License
MIT