Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
nano-banana-mcp
Nano Banana MCP server for generating and editing images with Google Gemini. No Gemini CLI required -- just an API key.
Quick Start
- Get a Gemini API key from Google AI Studio
- Add to your Claude Code settings (
~/.claude/settings.json) or Claude Desktop config:
{
"mcpServers": {
"nano-banana": {
"command": "npx",
"args": ["-y", "@daniel.barta/nano-banana-mcp"],
"env": {
"GEMINI_API_KEY": "your-api-key"
}
}
}
}- Restart Claude and ask it to generate an image.
Configuration
| Environment Variable | Required | Default | Description |
|---|---|---|---|
GEMINI_API_KEY | Yes | -- | Your Google AI API key |
GEMINI_MODEL | No | gemini-3.1-flash-image-preview | Gemini model for image generation/editing |
GEMINI_DESCRIBE_MODEL | No | gemini-2.5-flash | Gemini model for image description (text-only output) |
GEMINI_BASE_URL | No | -- | Custom base URL for Gemini API (proxy support) |
OUTPUT_DIR | No | ~/nano-banana-output | Directory for saved images |
Supported Models
| Model | Notes |
|---|---|
gemini-3.1-flash-image-preview | Default. Latest, fastest |
gemini-3-pro-image-preview | Higher quality, slower |
gemini-2.5-flash-image | Fast, cost-effective |
Tools
generate_image
Generate an image from a text prompt. Supports batch generation (up to 4 images). Response contains a thumbnail preview; full-res image is saved to disk.
| Parameter | Type | Required | Description |
|---|---|---|---|
prompt | string | Yes | Text description of the image |
aspectRatio | string | No | Aspect ratio (1:1, 1:4, 1:8, 2:3, 3:2, 3:4, 4:1, 4:3, 4:5, 5:4, 8:1, 9:16, 16:9, 21:9) |
size | string | No | Image size (512px, 1K, 2K, 4K) |
n | number | No | Number of images to generate (1-4, default 1) |
negativePrompt | string | No | Things to exclude from the generated image |
systemInstruction | string | No | System instruction to guide the model |
edit_image
Edit an existing image based on a text instruction. Supports multi-image input (up to 10 images total). Response contains a thumbnail preview; full-res image is saved to disk.
| Parameter | Type | Required | Description |
|---|---|---|---|
prompt | string | Yes | What to change |
filePath | string | Yes | Path to the source image |
additionalFilePaths | string[] | No | Additional image paths (up to 9) for multi-image editing |
aspectRatio | string | No | Aspect ratio (1:1, 1:4, 1:8, 2:3, 3:2, 3:4, 4:1, 4:3, 4:5, 5:4, 8:1, 9:16, 16:9, 21:9) |
size | string | No | Image size (512px, 1K, 2K, 4K) |
negativePrompt | string | No | Things to exclude from the edited image |
systemInstruction | string | No | System instruction to guide the model |
describe_image
Get a text description of an image.
| Parameter | Type | Required | Description |
|---|---|---|---|
filePath | string | Yes | Path to the image |
question | string | No | Specific question about the image |
systemInstruction | string | No | System instruction to guide the model |
Supported Input Formats
For edit_image and describe_image, the following image formats are supported:
JPEG, PNG, WebP, GIF, BMP, TIFF, SVG, HEIC/HEIF
File Path Resolution
When you provide a file path for editing or describing, the server searches for the file in this order:
- Absolute path as given
- Relative to the current working directory
- Relative to the output directory
- Basename only in the output directory
Thumbnails
To avoid hitting Claude Code's session file size limits, MCP responses contain thumbnail previews (max 512px, JPEG quality 80, ~20-50KB) instead of full-resolution images. Full-res images are always saved to disk at the path shown in the response metadata.
The first content block in generate/edit responses is a JSON metadata object:
{
"model": "gemini-3.1-flash-image-preview",
"count": 1,
"images": [
{ "filePath": "/Users/you/nano-banana-output/a-cat-1234567890.png", "mimeType": "image/png" }
]
}Development
git clone https://github.com/bartadaniel/nano-banana-mcp.git
cd nano-banana-mcp
npm install
npm run buildUse the local build in your config:
{
"mcpServers": {
"nano-banana": {
"command": "node",
"args": ["path/to/nano-banana-mcp/dist/index.js"],
"env": {
"GEMINI_API_KEY": "your-api-key"
}
}
}
}Testing
npm testRuns unit tests using Node.js built-in test runner (node:test). Tests cover error classes, all documented Gemini API response codes (BlockedReason, FinishReason), config shapes, image extraction edge cases, file operations, path security, and thumbnail generation.
License
MIT