🍌 nb-mcp — image generation MCP for Claude

A remote MCP server running on Cloudflare Workers that lets Claude generate images. Add it once as a custom connector and use it in Claude Design, claude.ai, and Claude Desktop.

• Free by default — uses Cloudflare Workers AI (Flux), no API key, no billing. Perfect for testing.
• Optional nano banana — switch to Google Gemini 2.5 Flash Image when you want (needs a key + billing).

One tool: generate_image (text → image), returned inline so Claude can see it.

---

Why Cloudflare Workers?

Claude's custom connectors are reached from Anthropic's cloud over the public internet, so the server must be hosted. Cloudflare Workers is a great fit: generous free tier, one-command deploy, and Workers AI gives free image models via the env.AI binding — so the default path needs no API key and no billing at all.

---

Deploy (≈2 minutes)

npm install
npx wrangler login          # opens a browser; or set CLOUDFLARE_API_TOKEN
npm run deploy

Wrangler prints your URL. The MCP endpoint is:

https://nb-mcp.<your-subdomain>.workers.dev/mcp

Open the root URL in a browser to confirm it's live. That's it — the default Workers AI backend works immediately on the free tier (no key needed).

Free tier: Workers AI includes a daily free allocation, enough for plenty of test images. Deploying the Worker itself is also free.

---

Add it to Claude

1. In Claude, go to Settings → Connectors (a.k.a. Customize → Connectors).
2. Click + Add custom connector.
3. Name: nano banana (anything). URL: your …/mcp URL.
4. Save (no OAuth needed — leave Advanced settings empty).
5. In a chat, open the + menu → Connectors and enable it, then ask Claude to make an image.

Try:

• “Generate an image of a neon cyberpunk street market, cinematic lighting.”
• “Make a flat-vector logo of a banana wearing sunglasses on white.”

---

Tool: generate_image

param	type	required	description
prompt	string	✅	What to draw. Be specific about subject, style, composition, colours, lighting, mood.
backend	workers-ai | nano-banana	–	Model to use. Default workers-ai (free Flux). nano-banana = Google Gemini (needs key).
steps	integer 1–8	–	Workers AI (Flux) diffusion steps. Higher = better/slower. Default 4.

---

Optional: enable nano banana (Gemini)

The repo keeps the original "nano banana" path as an option for when you want Google's model.

wrangler secret put GEMINI_API_KEY      # paste your Google Gemini key

Then either call the tool with backend: "nano-banana", or make it the default by setting NB_BACKEND = "nano-banana" under [vars] in wrangler.toml and redeploying.

⚠️ Gemini image generation requires billing. On Google's free tier the image model has a quota of 0 (you'll get HTTP 429). Enable billing on the project of your API key first. The default Workers AI backend has no such requirement.

---

Configuration

binding / var	where	purpose
AI	wrangler.toml [ai]	Workers AI binding (free image backend). Required for workers-ai.
GEMINI_API_KEY	wrangler secret put / .dev.vars	Only for the nano-banana backend.
NB_BACKEND	[vars]	Default backend: workers-ai (default) or nano-banana.
NB_WORKERS_MODEL	[vars]	Override Workers AI model (default @cf/black-forest-labs/flux-1-schnell).
NB_GEMINI_MODEL	[vars]	Override Gemini model (default gemini-2.5-flash-image).

---

Local development

npm install
npx wrangler login            # the AI binding always runs remotely, so dev needs auth too
npm run dev                   # http://localhost:8787  (endpoint: /mcp)

# in another terminal, verify the MCP protocol:
node scripts/smoke-test.mjs                                   # local
node scripts/smoke-test.mjs https://<worker>.workers.dev/mcp  # remote

For the nano-banana backend locally, copy .dev.vars.example → .dev.vars and add your key.

---

Security notes

• The default Workers AI backend needs no secret. A GEMINI_API_KEY (if used) is stored as a Cloudflare secret and never sent to Claude.
• The connector is unauthenticated by default — anyone with the URL can call it and use your Workers AI / Gemini quota. Keep the URL private, or add auth (Cloudflare Access in front of the Worker, or OAuth in the MCP layer).

---

How it works

Claude (Design / web / desktop)
        │  Streamable HTTP (MCP)  POST /mcp
        ▼
Cloudflare Worker  (src/index.ts)   ← stateless, hand-rolled MCP transport
        │
        ├─ backend "workers-ai" → env.AI.run(Flux)          ← free, no key
        └─ backend "nano-banana" → Gemini REST API          ← needs GEMINI_API_KEY + billing
        │
        ▼
   image returned inline to Claude

• Transport: stateless Streamable HTTP (POST /mcp, SSE response). No Durable Objects, no Redis.
• Runtime deps: none. Just Wrangler + TypeScript for tooling.