nano-banana-mcp

A Cloudflare Worker exposing Google's Gemini 2.5 Flash Image model ("nano banana") as an MCP tool, for use as a custom connector in Claude.ai.

Exposes two tools: generate_image(prompt, aspect_ratio?, count?, seed?, temperature?) and edit_image(image, instruction, aspect_ratio?, seed?, temperature?).

Connector URL format (once deployed):

https://nano-banana-mcp.<subdomain>.workers.dev/<MCP_AUTH_TOKEN>/mcp

See DEPLOY.md for first-time setup.

Parameters

generate_image

Param	Type	Required	Default	Notes
prompt	string	yes	—	Description of the image. Style direction belongs here.
aspect_ratio	enum	no	1:1	One of 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9.
count	integer	no	1	1–4. Each variation is a separate billed generation with its own URL.
seed	integer	no	random, always reported	int32. Same prompt + ratio + temperature + seed reproduces the same image. With count > 1 the seed is incremented per variation (seed, seed+1, …).
temperature	number	no	model default	0–2. Lower is more literal, higher more inventive.

num_images is still accepted as a deprecated alias for count, so clients holding a cached copy of the old tool definition keep working.

edit_image

Param	Type	Required	Default	Notes
image	string	yes	—	Public HTTPS URL, or the 8-character id from a previous result.
instruction	string	yes	—	The edit to perform, e.g. "make it dusk".
aspect_ratio	enum	no	source framing	Same values as above. Omit to leave the framing alone.
seed	integer	no	random, always reported	int32, as above.
temperature	number	no	model default	0–2, as above.

An invalid enum value or an out-of-range number comes back as an isError result naming the valid values, without spending a Gemini call.

How the parameters reach Gemini

All of them go into generationConfig on the generateContent body — the aspect ratio specifically into generationConfig.imageConfig.aspectRatio:

{
  "contents": [...],
  "generationConfig": {
    "temperature": 0.9,
    "seed": 4821,
    "responseModalities": ["TEXT", "IMAGE"],
    "imageConfig": { "aspectRatio": "16:9" }
  }
}

temperature is omitted from the body entirely when not supplied, so the model's own default applies. seed never is — see below. Earlier versions of this server instead appended (aspect ratio 16:9) to the prompt text, which left the ratio a suggestion the model was free to ignore — that is why 16:9 requests kept coming back square. count is handled as sequential generateContent calls rather than one call asking for N images, which the model answers inconsistently.

Settings echo

Every image comes back as its own text content block: the URL on the first line, then the settings it was actually produced under, so the chat side can report them and reuse them in a follow-up request.

https://nano-banana-mcp.<subdomain>.workers.dev/<token>/img/8be62d09
variant 2/3 · 1376×768 (16:9) · seed 101 · temp 0.9

The seed is always present. A caller who omits seed gets one generated by the Worker, which is sent to Gemini and reported back. Letting the model pick its own unreported seed would make the image impossible to reproduce, so refinement — "same image but at dusk" — would be impossible too. temperature reads temp default when it wasn't supplied, since there is no single number to name.

1376×768 (16:9) · seed 868960483 · temp default

The resolution is read from the returned image's own header rather than assumed from the requested ratio, so if the model ignores the aspect ratio the line says so:

1024×1024 (16:9) ⚠ model returned a different aspect ratio than the requested 16:9

When no aspect_ratio was requested — the usual case for edit_image — the ratio in the line is inferred from the returned pixels instead, and never carries the mismatch warning.

If a variation fails partway through a count > 1 batch, the images already generated are still returned, with a trailing note naming the variation that failed and why.

Image URLs

Since Claude.ai doesn't render raw base64 image blocks from custom MCP connectors, generate_image also stores each generated image in a Workers KV namespace (IMAGES) and returns a public URL alongside the base64 content:

https://nano-banana-mcp.<subdomain>.workers.dev/<MCP_AUTH_TOKEN>/img/<id>

• Each image is available at its URL for 24 hours, after which it expires from KV and the route returns a 404.
• The URL is auth-gated the same way as /mcp: the token must match MCP_AUTH_TOKEN.

Rendering

Tool results are plain MCP content blocks — one text block per image (URL + settings) followed by the raw image blocks — and the chat side decides how to display them. The server declares no resources capability and no MCP Apps extension, so no host-rendered widget is involved.

Editing

edit_image edits an existing image with a natural-language instruction, using the same Gemini 2.5 Flash Image model. The source image argument accepts either:

• a public HTTPS URL to an image, or
• the 8-character id from a previous generate_image/edit_image result (the trailing segment of its returned /img/<id> URL).

If aspect_ratio is omitted, no imageConfig is sent at all and the source image's framing is preserved. Source images are capped at ~6 MB. Like generate_image, results are stored in KV and returned as URL(s) + raw image content, so edited images can themselves be passed back into edit_image by id for further edits.