gemini-nano-banana-mcp

A global MCP (Model Context Protocol) server that gives Claude Code the ability to generate images using Google's Gemini image generation models. When registered globally, Claude proactively generates visuals — UI mockups, diagrams, visualizations, concept art — whenever a response would benefit from one.

Features

• Multi-model support — Choose between Pro (highest quality), Flash (cheapest), and Flash-2 (balanced)
• Prompt sanitization — 28 regex patterns block API keys, tokens, env vars, PEM blocks, DB connection strings, JWTs, and other sensitive data before they reach Google's servers
• Output safety filter — Model-returned text and SDK error messages are quarantined so they can never leak into MCP tool output (the LLM-trusted channel)
• Rate limiting — Configurable sliding-window limiter (default: 20 requests/hour)
• Date-bucketed output — Images saved to ~/generated-images/YYYY/MM/DD/ with collision-safe filenames
• Inline display — Returns images as base64 for inline rendering in Claude Code, plus saves to disk
• Configurable output — Custom output directories, filenames, aspect ratios, and resolutions
• Dual transport — Stdio for local Claude Code use, HTTP for cloud deployment with Docker
• Security hardened — Timing-safe auth, request body limits, session TTL reaping, HTTP request timeouts

Prerequisites

• Node.js 20+ (via NVM or direct install)
• pnpm package manager
• Google Gemini API key — Get one at Google AI Studio

Get started

Choose your path based on how you want to run the server:

1. Quick install via Claude — Let Claude Code handle the clone, build, and registration. Easiest if you already use Claude Code.
2. Manual install — Clone, build, and register the stdio server with your MCP client of choice. Works with Claude Code, Claude Desktop, Cursor, VS Code, and other MCP clients.
3. Docker / cloud deployment — Run the server as an HTTP service in a container, locally or on a cloud provider, then connect remote clients via the Streamable HTTP transport.

Option 1: Quick install via Claude

Paste this prompt into Claude Code and it will handle the clone, build, and registration for you. You only need your Gemini API key ready.

Please install the gemini-nano-banana-mcp server for me:

1. Clone https://github.com/kevinkiklee/gemini-nano-banana-mcp into the folder the user specifies
2. Run `pnpm install` and `pnpm build` inside it
3. Register it as a global MCP server in ~/.claude.json under the `mcpServers` key with name `gemini-nano-banana`, type `stdio`, command `node`, and args pointing to the absolute path of `dist/server/index.js`
4. Add a `GEMINI_API_KEY` env var to the server config — ask me for the key
5. Optionally add a `RATE_LIMIT_PER_HOUR` env var (default 20)
6. Tell me to restart Claude Code when you're done

Do not write the API key anywhere on disk other than ~/.claude.json, and do not echo it back to me.

Option 2: Manual install

1. Clone and install

git clone https://github.com/kevinkiklee/gemini-nano-banana-mcp.git
cd gemini-nano-banana-mcp
pnpm install

2. Build

pnpm build

This compiles TypeScript to dist/server/index.js.

3. Register with your MCP client

Replace /absolute/path/to/gemini-nano-banana-mcp with the path you cloned into, and set your Gemini API key.

<details> <summary><strong>Claude Code</strong></summary>

Run in terminal:

claude mcp add gemini-nano-banana \
  -e GEMINI_API_KEY=<your-gemini-api-key> \
  -s user \
  -- node /absolute/path/to/gemini-nano-banana-mcp/dist/server/index.js

Or add manually to ~/.claude.json (create the file if it doesn't exist):

{
  "mcpServers": {
    "gemini-nano-banana": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/gemini-nano-banana-mcp/dist/server/index.js"],
      "env": {
        "GEMINI_API_KEY": "<your-gemini-api-key>",
        "RATE_LIMIT_PER_HOUR": "20"
      }
    }
  }
}

</details>

<details> <summary><strong>Claude Desktop</strong></summary>

Open Settings → Developer → Edit Config, or edit the config file directly:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add to mcpServers:

{
  "mcpServers": {
    "gemini-nano-banana": {
      "command": "node",
      "args": ["/absolute/path/to/gemini-nano-banana-mcp/dist/server/index.js"],
      "env": {
        "GEMINI_API_KEY": "<your-gemini-api-key>"
      }
    }
  }
}

</details>

<details> <summary><strong>Cursor</strong></summary>

Open Cursor Settings → MCP → + Add new MCP server, or edit ~/.cursor/mcp.json directly:

{
  "mcpServers": {
    "gemini-nano-banana": {
      "command": "node",
      "args": ["/absolute/path/to/gemini-nano-banana-mcp/dist/server/index.js"],
      "env": {
        "GEMINI_API_KEY": "<your-gemini-api-key>"
      }
    }
  }
}

</details>

<details> <summary><strong>VS Code</strong></summary>

Open Command Palette (Cmd+Shift+P / Ctrl+Shift+P) → MCP: Open User Configuration → add:

{
  "servers": {
    "gemini-nano-banana": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/gemini-nano-banana-mcp/dist/server/index.js"],
      "env": {
        "GEMINI_API_KEY": "<your-gemini-api-key>"
      }
    }
  }
}

</details>

<details> <summary><strong>Other clients</strong></summary>

For any MCP-compatible client that supports stdio servers, configure it to launch:

node /absolute/path/to/gemini-nano-banana-mcp/dist/server/index.js

with GEMINI_API_KEY set in the environment. Refer to your client's MCP configuration docs for the exact file format. </details>

4. Add behavioral nudge to CLAUDE.md (optional)

Add this to your global ~/CLAUDE.md so Claude proactively uses the tool:

## Image Generation

A `generate_image` MCP tool is available globally via the gemini-nano-banana
MCP server. Use it proactively when a response would genuinely benefit from
a visual — e.g., UI mockups, diagrams, data visualizations, concept art, or
when the user is discussing something inherently visual.

**When to generate:** The user is discussing UI/UX, asking about visual
design, describing something spatial or visual, or when a picture would
communicate more effectively than text.

**When NOT to generate:** Purely textual conversations, code-focused
discussions, rapid back-and-forth Q&A, or when the user has explicitly asked
you not to generate images.

5. Restart Claude Code

Restart any running Claude Code sessions to pick up the new MCP server.

Option 3: Docker / cloud deployment

The server ships with a Dockerfile for containerized deployment. In Docker mode, the server runs over HTTP using the MCP Streamable HTTP transport instead of stdio, with per-session isolation, bearer token auth, and automatic session cleanup.

Run locally with Docker

docker build -t gemini-nano-banana-mcp .

docker run -p 3000:3000 \
  -e GEMINI_API_KEY=<your-gemini-api-key> \
  -e MCP_AUTH_TOKEN=<a-secret-token> \
  gemini-nano-banana-mcp

Verify it's running:

curl http://localhost:3000/health
# {"status":"ok","sessions":0,"uptime":1.234}

To persist generated images outside the container, mount a volume. The default output_dir (~/generated-images/) resolves to /home/node/generated-images inside the container:

docker run -p 3000:3000 \
  -e GEMINI_API_KEY=<your-gemini-api-key> \
  -e MCP_AUTH_TOKEN=<a-secret-token> \
  -v $(pwd)/output:/home/node/generated-images \
  gemini-nano-banana-mcp

Deploy to a cloud provider

The Docker image runs on any platform that supports containers. Build and push to your registry, then deploy with your provider's CLI or dashboard.

Build and push:

docker build -t gemini-nano-banana-mcp .
docker tag gemini-nano-banana-mcp your-registry.example.com/gemini-nano-banana-mcp:latest
docker push your-registry.example.com/gemini-nano-banana-mcp:latest

Deploy — pick your platform:

# Google Cloud Run
gcloud run deploy gemini-nano-banana-mcp \
  --image your-registry.example.com/gemini-nano-banana-mcp:latest \
  --set-env-vars GEMINI_API_KEY=<key>,MCP_AUTH_TOKEN=<secret> \
  --port 3000

# AWS ECS (after creating a task definition with the image)
aws ecs create-service --cluster my-cluster \
  --service-name banana-mcp --task-definition banana-mcp:1

# Azure Container Apps
az containerapp create --name banana-mcp \
  --image your-registry.example.com/gemini-nano-banana-mcp:latest \
  --env-vars GEMINI_API_KEY=<key> MCP_AUTH_TOKEN=<secret> \
  --target-port 3000

# Fly.io
fly launch --image your-registry.example.com/gemini-nano-banana-mcp:latest
fly secrets set GEMINI_API_KEY=<key> MCP_AUTH_TOKEN=<secret>

# Railway (from repo root)
railway up

Connect an MCP client to the remote server:

Once deployed, point your MCP client at the HTTP endpoint. Replace https://your-deployment-url.example.com and <your-MCP_AUTH_TOKEN> with your values.

<details> <summary><strong>Claude Code</strong></summary>

Run in terminal:

claude mcp add --transport http gemini-nano-banana \
  https://your-deployment-url.example.com/mcp \
  --header "Authorization: Bearer <your-MCP_AUTH_TOKEN>" \
  --scope user

Or add manually to ~/.claude.json:

{
  "mcpServers": {
    "gemini-nano-banana": {
      "type": "streamable-http",
      "url": "https://your-deployment-url.example.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-MCP_AUTH_TOKEN>"
      }
    }
  }
}

</details>

<details> <summary><strong>Cursor</strong></summary>

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "gemini-nano-banana": {
      "type": "http",
      "url": "https://your-deployment-url.example.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-MCP_AUTH_TOKEN>"
      }
    }
  }
}

</details>

<details> <summary><strong>VS Code</strong></summary>

Open Command Palette → MCP: Open User Configuration → add:

{
  "servers": {
    "gemini-nano-banana": {
      "type": "http",
      "url": "https://your-deployment-url.example.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-MCP_AUTH_TOKEN>"
      }
    }
  }
}

</details>

<details> <summary><strong>Other clients</strong></summary>

For any MCP-compatible client that supports the Streamable HTTP transport, point it at https://your-deployment-url.example.com/mcp with the Authorization: Bearer <your-MCP_AUTH_TOKEN> header.

If your client doesn't support remote MCP servers, use a proxy like mcp-remote:

{
  "mcpServers": {
    "gemini-nano-banana": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-deployment-url.example.com/mcp",
        "--header",
        "Authorization: Bearer <your-MCP_AUTH_TOKEN>"
      ]
    }
  }
}

</details>

Run HTTP mode without Docker

If you prefer to run the HTTP server directly on a host with Node.js:

pnpm install && pnpm build

GEMINI_API_KEY=<key> MCP_AUTH_TOKEN=<secret> PORT=3000 node dist/server/http.js

HTTP endpoints

Method	Path	Auth	Description
GET	/health	No	Health check — returns { status, sessions, uptime }
POST	/mcp	Yes	MCP messages (initialize, tool calls)
GET	/mcp	Yes	SSE stream for server-to-client notifications
DELETE	/mcp	Yes	Explicit session teardown

Configuration

Environment Variables

Variable	Required	Default	Description
GEMINI_API_KEY	Yes	—	Your Google Gemini API key
MCP_AUTH_TOKEN	No	—	Bearer token for HTTP auth (strongly recommended when deployed)
PORT	No	3000	HTTP server listen port
HOST	No	0.0.0.0	HTTP server listen address
RATE_LIMIT_PER_HOUR	No	20	Max image generations per hour (per session in HTTP mode)
LOG_LEVEL	No	info	Log verbosity (debug or info)

Tool Reference

generate_image

Generates an image using Google Gemini and returns it inline with a saved file path.

Parameter	Type	Default	Description
prompt	string	(required)	Image generation prompt (1-10,000 chars). Prompts containing detected secrets are blocked.
model	"pro" | "flash" | "flash-2"	"pro"	Model selection (see below)
aspect_ratio	string	"1:1"	One of: 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
size	"512" | "1K" | "2K" | "4K"	"1K"	Output resolution. 512 is fastest/cheapest; 4K is highest fidelity.
google_search	boolean	false	Enable grounded generation via Google Search
output_dir	string	"~/generated-images/"	Output directory. Must resolve to a path within $HOME — paths outside $HOME (e.g. /tmp, /etc) are rejected. ~/ is expanded; relative paths are resolved from the current working directory.
filename	string	(auto)	Custom filename without extension. 1-200 chars; must contain at least one alphanumeric. Path separators, .., and control characters are stripped.

Models

Key	Gemini Model ID	Best For
pro	gemini-3-pro-image-preview	Highest quality output
flash	gemini-2.5-flash-image	Fast and cheapest
flash-2	gemini-3.1-flash-image-preview	Balanced quality/speed

Cost tip: Use model="flash" and size="512" for quick drafts. Reserve model="pro" and larger sizes for final output.

• Prompt sanitization — 28 regex patterns scan every prompt for API keys (OpenAI, Google, AWS, Stripe, Anthropic, GitHub), tokens (Slack, GitLab, JWT, Bearer), PEM private keys, DB connection strings with embedded credentials, env vars, sensitive paths, and long base64 blobs. Matching prompts are blocked with an error.
• Untrusted-output quarantine — Text that Gemini returns in place of an image is sanitized (ANSI/control chars/bidi overrides stripped) and only logged — never embedded into tool output, where the calling LLM would treat it as trusted context.
• Error-message allowlist — Only static error strings thrown by our own code reach the MCP channel. Raw SDK exception messages and non-Error rejections are replaced with a generic placeholder and logged separately.
• Timing-safe auth — Bearer token comparison uses crypto.timingSafeEqual to prevent timing oracle attacks.
• Request body limits — POST bodies are capped at 1 MB to prevent out-of-memory denial-of-service.
• HTTP request timeouts — 30-second request timeout prevents Slowloris-style connection exhaustion.
• Session management — Idle HTTP sessions are automatically reaped after 30 minutes. Graceful shutdown closes all sessions before exit.
• Path validation — Output directories are restricted to within $HOME. Path traversal attempts (../) are rejected.
• Filename sanitization — Control characters are stripped first, then path separators and traversal patterns, preventing bypass via embedded null bytes.
• File permissions — Generated images are written with 0o600 (owner-only read/write). Output directories are created with 0o700.
• No credential logging — The API key is only used at SDK initialization time and never logged.

Local Development

Commands

pnpm build          # Compile TypeScript to dist/
pnpm typecheck      # Type-check without emitting (CI gate)
pnpm dev            # Run stdio transport with tsx (no build needed)
pnpm dev:http       # Run HTTP transport with tsx (no build needed)
pnpm serve          # Run HTTP transport from compiled dist/
pnpm test           # Run all tests with Vitest
pnpm test:watch     # Run tests in watch mode
pnpm test:coverage  # Run tests with coverage report

Development workflow

1. Edit source modules under src/
2. Test with pnpm test — 175+ tests cover utilities, sanitization, rate limiting, API wrapper, tool handler, and full HTTP integration
3. Build with pnpm build — required before the registered MCP server picks up changes
4. Restart Claude Code to reload the MCP server with your changes

Testing with MCP Inspector

You can test the server interactively without Claude Code using the MCP Inspector:

GEMINI_API_KEY=<your-key> npx @modelcontextprotocol/inspector node dist/server/index.js

This opens a web UI where you can call generate_image directly and inspect the request/response.

Architecture

src/
  utils.ts              File/path utilities (slugify, sanitize, expand, unique filepath)
  secret-patterns.ts    Single source of truth for credential-shape regexes
  security.ts           scanForSecrets, RateLimiter class
  sanitize.ts           quarantineModelText + safeErrorMessage (untrusted-output filters)
  gemini.ts             MODEL_MAP, callGemini wrapper, lazy client singleton, resetClient
  gemini-types.ts       Gemini API type definitions
  utils.test.ts
  security.test.ts
  sanitize.test.ts
  gemini.test.ts
  server/
    server.ts           log(), Zod schema, ToolResult type, createMcpServer() factory
    handler.ts          handleGenerateImage() pure tool handler
    index.ts            Stdio entry point (local / Claude Code)
    http.ts             HTTP server setup, auth gate (timing-safe), main()
    http-routes.ts      MCP POST/GET/DELETE route handlers
    http-helpers.ts     Session registry (with TTL), readBody (1MB limit), json helper
    lifecycle.ts        Session reaper, graceful shutdown
    server.test.ts
    http.test.ts

Both entry points call createMcpServer() from server/server.ts to get a fully configured McpServer with the generate_image tool registered. The stdio entry point (server/index.ts) connects via StdioServerTransport for local use. The HTTP entry point (server/http.ts) uses StreamableHTTPServerTransport with stateful per-session isolation for cloud deployment.

All source files are kept under 150 lines. If a module approaches the limit, it is split into focused sub-modules.

Output Structure

Generated images are organized by date:

~/generated-images/
  2026/
    04/
      05/
        a-sunset-over-mountains-2026-04-05T14-30-22.png
        ui-mockup-dashboard-2026-04-05T15-12-08.png

Filenames are auto-generated from a slugified prompt + ISO timestamp. If a collision occurs, a counter suffix is appended (-1, -2, etc.).

Contributing

1. Fork the repo
2. Create a feature branch (git checkout -b my-feature)
3. Make your changes with tests (pnpm test)
4. Ensure the build passes (pnpm build)
5. Keep all source files under 150 lines
6. Open a pull request

License

MIT