# tasopen/mcp-alphabanana [Health: Active]

**Category:** 🎨 Art & Culture  
**Repository:** https://github.com/tasopen/mcp-alphabanana  
**GitHub Stars:** 9  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/tasopen-mcp-alphabanana

## Description
Local MCP server for generating image assets with Google Gemini (Nano Banana 2 / Pro). Supports transparent PNG/WebP output, exact resizing/cropping, up to 14 reference images, and Google Search grounding.

## Tools
Capabilities this server exposes over MCP:

- **model** — `Flash3.1`, `Lite3.1`, `Flash2.5`, `Pro3`, `flash`, `pro`
- **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

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "mcp-alphabanana": {
    "command": "npx",
    "args": ["-y","@tasopen/mcp-alphabanana"],
    "env": {
      "GEMINI_API_KEY": ""
    }
  }
}
```

**Requires environment variables:** `GEMINI_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What tasopen/mcp-alphabanana MCP server does

The tasopen/mcp-alphabanana MCP server exposes a `generate_image` tool for creating image assets with Google Gemini. An agent supplies a prompt and output settings, then receives either a saved file, encoded image data, or both. The tool is suited to workflows that generate illustrations, game assets, visual drafts, or other raster images from natural-language instructions.

Several Gemini image model choices are available. `Flash3.1` is the default and supports thinking and grounding controls; `Lite3.1` is limited to 1K output; `Flash2.5` provides a legacy Flash option; and `Pro3` targets higher-fidelity generation. `flash` and `pro` remain available as aliases.

## How it works

The server runs locally and sends generation requests to Google Gemini using the configured API key. The request can specify a prompt, model, output resolution, dimensions, aspect ratio, format, resize behavior, and delivery mode. Normal mode resizes the generated result to `outputWidth` and `outputHeight`. With `noresize=true`, the response keeps Gemini’s native dimensions and requires both an `aspectRatio` and `output_resolution` value.

Generated images can be returned as PNG, JPG, or WebP. File and combined responses require an absolute `outputPath`; base64 responses place the image data in the MCP result. For Claude Desktop, file output is recommended for medium or large images because base64 and combined responses can consume substantial client context.

Local reference files can guide the generation. The tool accepts up to 14 references for the newer supported models and up to three for Flash2.5. Flash3.1 can also use text or image grounding and can include reasoning or grounding metadata when those options are enabled. Lite3.1 does not support Search Grounding.

## Setup and configuration

Install and start the tasopen/mcp-alphabanana MCP server with `npx -y @tasopen/mcp-alphabanana`. Set `GEMINI_API_KEY` in the MCP client environment before launching it. The same variable can be mapped from the operating system environment in an MCP configuration, or supplied directly in that configuration.

The repository also provides an MCPB download for Claude Desktop. Claude Desktop users can add the downloaded package as an extension. On Windows, the documentation recommends adding a FileSystem extension when the workflow needs to select local reference files or writable output paths. Cursor and VS Code are also listed as compatible MCP clients.

## Tools and capabilities

The single exposed tool, `generate_image`, supports:

- Model selection across Lite, Flash, and Pro variants.
- `0.5K`, `1K`, `2K`, and `4K` resolution settings where supported.
- Exact width and height output with crop, stretch, letterbox, or contain resizing.
- PNG, JPG, and WebP output.
- Transparent PNG or WebP post-processing with configurable color tolerance and fringe handling.
- File, base64, or combined delivery.
- Up to 14 local reference images for supported models.
- Optional Flash3.1 thinking, grounding, reasoning fields, and metadata.

The `outputFileName` parameter is required, and its extension can be added automatically when omitted. Debug mode can save intermediate artifacts. Transparency processing is intended for PNG and WebP; JPG does not support an alpha channel.

## Limitations and notes

The server depends on Google Gemini access and a valid `GEMINI_API_KEY`; the repository does not describe a built-in free generation service. Model features vary, so grounding and thinking controls should be used with Flash3.1, while Lite3.1 is restricted to 1K output and has no Search Grounding.

Large encoded responses may exceed an MCP client’s context limits, making file output a better choice for larger assets. Reference images must be local files, and output directories must be writable absolute paths. The project is released under the MIT license. The tasopen/mcp-alphabanana MCP server is therefore most appropriate when the client can access local files and the workflow can provide Google Gemini credentials.

_Full upstream README: https://allmcps.com/mcp/tasopen-mcp-alphabanana/readme_