{
"markdown": "# mcp-nano-banana\n\nMCP server for AI-powered image generation using Google Gemini Nano Banana models. Generate, edit, and combine images from text prompts — directly from your AI coding assistant.\n\n\n\n\n## Features\n\n- **Text-to-image generation** — Create images from natural language descriptions\n- **Image editing** — Upload images and modify them with text instructions\n- **Multi-image combination** — Mix up to 14 reference images into one composite\n- **Resolution control** — Generate at 512px, 1K, 2K, or 4K resolution\n- **13+ aspect ratios** — From square (1:1) to ultra-wide (21:9) and tall (1:8)\n- **Auto-fallback** — Pro model falls back to Flash on rate limits (429/403/402)\n- **File output** — Save to specific paths or return inline base64\n- **Favicon generation** — Generate complete favicon packages with one command\n- **Multi-format output** — PNG, JPEG, and WebP support\n\n## Quick Start\n\n### Prerequisites\n\n1. **Get a Gemini API key** from [Google AI Studio](https://aistudio.google.com/apikey)\n2. **Enable billing** on your Google Cloud project — image generation requires a paid tier (~$0.04-0.05/image for NB2 at standard resolution)\n\n### Installation\n\n```bash\nnpm install -g mcp-nano-banana\n```\n\nSet your API key:\n\n```bash\nexport GEMINI_API_KEY=your-api-key\n```\n\nFor MCP Registry publication metadata, the registry name is `io.github.codeFi/mcp-nano-banana`.\n\n## MCP Configuration\n\n### Codex\n\n```bash\ncodex mcp add nano-banana --env GEMINI_API_KEY=your-api-key -- npx -y mcp-nano-banana@latest\n```\n\nOr add manually to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.nano-banana]\ncommand = \"npx\"\nargs = [\"-y\", \"mcp-nano-banana@latest\"]\n\n[mcp_servers.nano-banana.env]\nGEMINI_API_KEY = \"your-api-key\"\n```\n\n### Qwen Code\n\nAdd to `~/.qwen/settings.json`:\n\n```json\n{\n \"mcpServers\": {\n \"nano-banana\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"mcp-nano-banana@latest\"],\n \"env\": {\n \"GEMINI_API_KEY\": \"your-api-key\"\n }\n }\n }\n}\n```\n\n### Claude Code\n\n```bash\nclaude mcp add nano-banana -e GEMINI_API_KEY=your-api-key -- npx -y mcp-nano-banana@latest\n```\n\nOr add manually to `~/.claude/claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"nano-banana\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"mcp-nano-banana@latest\"],\n \"env\": {\n \"GEMINI_API_KEY\": \"your-api-key\"\n }\n }\n }\n}\n```\n\n### Other MCP Clients\n\nFor CLIs and desktop clients that use the standard `mcpServers` JSON format, register:\n\n```json\n{\n \"mcpServers\": {\n \"nano-banana\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"mcp-nano-banana@latest\"],\n \"env\": {\n \"GEMINI_API_KEY\": \"your-api-key\"\n }\n }\n }\n}\n```\n\n### Local / Development Build\n\n```bash\ngit clone https://github.com/codeFi/mcp-nano-banana.git\ncd mcp-nano-banana\nnpm install\nnpm run build\n```\n\nThen register with your MCP client:\n\n```json\n{\n \"mcpServers\": {\n \"nano-banana\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/mcp-nano-banana/dist/index.js\"],\n \"env\": {\n \"GEMINI_API_KEY\": \"your-api-key\"\n }\n }\n }\n}\n```\n\n## Models\n\n| Model | MCP Name | Description | Max Ref Images |\n|-------|----------|-------------|----------------|\n| `gemini-3-pro-image-preview` | Nano Banana Pro | High quality, thinking mode, professional assets | 6 object + 5 character |\n| `gemini-3.1-flash-image-preview` | Nano Banana 2 | Fast, high-efficiency, 1:4/4:1/1:8/8:1 ratios | 10 object + 4 character |\n| `gemini-2.5-flash-image` | Nano Banana | Fastest, optimized for high-volume tasks | - |\n\nThe server defaults to **Nano Banana Pro** for best quality and automatically falls back to Flash on rate limits.\n\n## Available Parameters\n\n### Resolution\n\n| Value | Approx. Pixels | Supported Models |\n|-------|---------------|------------------|\n| `\"512\"` | ~512px | Nano Banana 2 only |\n| `\"1K\"` | ~1024px | All models |\n| `\"2K\"` | ~2048px | All models |\n| `\"4K\"` | ~4096px | All models |\n\nDefault: `\"1K\"`\n\n### Aspect Ratio\n\n| Value | Dimensions at 1K | Common Use Case |\n|-------|-----------------|-----------------|\n| `1:1` | 1024×1024 | Social posts, icons |\n| `16:9` | 1344×768 | Headers, presentations |\n| `9:16` | 768×1344 | Stories, mobile |\n| `4:3` | 1152×896 | Desktop, photos |\n| `3:4` | 896×1152 | Portraits |\n| `2:3` | ~896×1344 | Print, magazines |\n| `3:2` | ~1344×896 | Photos |\n| `4:5` | ~896×1120 | Instagram posts |\n| `5:4` | ~1120×896 | Instagram landscape |\n| `21:9` | ~2048×878 | Ultra-wide banners |\n| `1:4` | ~512×2048 | Nano Banana 2 only — tall strips |\n| `4:1` | ~2048×512 | Nano Banana 2 only — wide strips |\n| `1:8` | ~512×4096 | Nano Banana 2 only — extra tall |\n| `8:1` | ~4096×512 | Nano Banana 2 only — extra wide |\n\n## Tools\n\n### `generate_image`\n\nGenerate or edit images from text prompts.\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `prompt` | string | ✅ Yes | — | Text description or editing instructions |\n| `imagePaths` | string[] | No | — | Reference image paths on disk (up to 14) |\n| `model` | string | No | `gemini-3-pro-image-preview` | Model to use |\n| `aspectRatio` | string | No | `1:1` | See table above for all options |\n| `resolution` | string | No | `1K` | `512`, `1K`, `2K`, or `4K` |\n| `outputFormat` | string | No | `png` | `png`, `jpeg`, `webp` |\n| `outputPath` | string | No | — | Save image to this file path |\n\n#### Examples\n\n**Generate from text:**\n```json\n{\n \"prompt\": \"A sunset over mountains with dramatic lighting\",\n \"aspectRatio\": \"16:9\",\n \"resolution\": \"2K\",\n \"outputPath\": \"/Users/currentUser/Desktop/sunset.png\"\n}\n```\n\n**Edit an existing image:**\n```json\n{\n \"prompt\": \"Change the background to a coffee shop interior\",\n \"imagePaths\": [\"/Users/currentUser/photo.jpg\"],\n \"outputPath\": \"/Users/currentUser/edited.png\"\n}\n```\n\n**Combine multiple images:**\n```json\n{\n \"prompt\": \"Put these glasses on this person's face\",\n \"imagePaths\": [\"/path/to/face.jpg\", \"/path/to/glasses.jpg\"],\n \"outputPath\": \"/path/to/result.png\"\n}\n```\n\n**High-res wallpaper:**\n```json\n{\n \"prompt\": \"A futuristic cityscape at night with neon lights and rain\",\n \"aspectRatio\": \"16:9\",\n \"resolution\": \"4K\",\n \"outputPath\": \"/path/to/wallpaper.png\"\n}\n```\n\n### `generate_favicons`\n\nGenerate a complete favicon package from a prompt or existing image.\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `prompt` | string | No\\* | — | Icon description (required if `imagePath` not set) |\n| `imagePath` | string | No\\* | — | Path to existing master icon image |\n| `model` | string | No | `gemini-3-pro-image-preview` | Model for prompt generation |\n| `outputDir` | string | No | — | Directory for individual favicon files |\n| `outputPath` | string | No | — | Save ZIP package to this path |\n| `returnZipBase64` | boolean | No | `false` | Return ZIP as base64 text |\n| `appName` | string | No | `My App` | Manifest `name` |\n| `shortName` | string | No | `App` | Manifest `short_name` |\n| `themeColor` | string | No | `#ffffff` | Manifest theme color |\n| `backgroundColor` | string | No | `#ffffff` | Manifest background color |\n| `includeReadme` | boolean | No | `true` | Include README.md in package |\n\n#### Example\n\n```json\n{\n \"prompt\": \"A minimalist banana icon with a soft gradient\",\n \"outputDir\": \"/path/to/favicon\",\n \"outputPath\": \"/path/to/favicon.zip\",\n \"appName\": \"MyBrand\",\n \"shortName\": \"Brand\",\n \"themeColor\": \"#1a1a2e\",\n \"backgroundColor\": \"#ffffff\"\n}\n```\n\n**Generated files:**\n- `favicon.ico` — Multi-size icon (16/32/48px)\n- `favicon-16x16.png` — Browser tabs\n- `favicon-32x32.png` — Higher-res tabs\n- `apple-touch-icon.png` — iOS home screen\n- `android-chrome-192x192.png` — Android\n- `android-chrome-512x512.png` — Android HD\n- `site.webmanifest` — PWA manifest\n\n**HTML snippet (included in response):**\n```html\n\n\n\n\n\n```\n\n## Pricing\n\nImage generation requires a **paid Google AI Studio account**. Approximate costs:\n\n| Model | 1K | 2K | 4K |\n|-------|-----|-----|-----|\n| Nano Banana 2 | ~$0.04 | ~$0.08 | ~$0.15 |\n| Nano Banana Pro | ~$0.06 | ~$0.13 | ~$0.24 |\n\nYou only pay for what you generate — no monthly minimum.\n\n## Supported Image Formats\n\n**Input (reference images):** `png`, `jpg`, `jpeg`, `webp`, `gif`\n**Output:** `png`, `jpeg`, `webp`\n\n## Development\n\n```bash\n# Build TypeScript\nnpm run build\n\n# Watch mode\nnpm run dev\n\n# Run tests\nnpm test\n\n# Run the server directly\nnode dist/index.js\n```\n\n## Troubleshooting\n\n| Issue | Solution |\n|-------|----------|\n| `GEMINI_API_KEY is not set` | Export the env var or add it to your MCP config |\n| `429 Too Many Requests` | Server auto-falls back to Flash model. Add billing to your account. |\n| `403/402 Quota exceeded` | Enable billing at [Google Cloud Console](https://console.cloud.google.com/billing) |\n| `503 Unavailable` | High demand — retry in a moment. Common with 4K requests. |\n| Image not updating after edit | Make sure you rebuilt the TypeScript (`npm run build`) |\n| `imagePaths` not found | Use absolute paths. Relative paths may not resolve correctly. |\n\n## Architecture\n\n```\nAI Assistant (MCP Client)\n │ (MCP Protocol over stdio)\n ▼\nmcp-nano-banana Server\n │ (HTTPS POST)\n ▼\nGoogle Gemini API\n │\n ▼\nGenerated Image → saved to outputPath (or returned inline base64)\n```\n\n## License\n\n[MIT](LICENSE)\n\n## Author\n\n[codeFi](https://github.com/codeFi)\n",
"bytes": 9821,
"sha": "e7e09e1693feda4ca3183580d5edd01230f19bf83af822dd06f8472cd12b017a",
"repo_slug": "codefi/mcp-nano-banana",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_codefi_mcp_nano_banana_112b626c/readme"
}