image-mcp

An MCP server on Cloudflare Workers that gives Claude image generation across Google (Nano Banana), OpenAI (GPT Image) and Reve behind one set of tools — with a hard spend cap, cost reporting on every call, and URLs instead of megabytes of base64.

Works with Claude Code, Claude Desktop and claude.ai (Custom Connectors) over the same streamable-HTTP endpoint.

Why it is shaped this way

It returns URLs, not bytes. Both provider families hand back base64. A 1024×1024 PNG is ~1.4 MB, ~1.9 MB as base64, roughly 500k tokens if you pass it back as text — well past MAX_MCP_OUTPUT_TOKENS (25k default). Images are persisted to R2 and the tool returns {url, model, cost_usd, budget}.

When the model does need to see the image, return_inline: true returns a downscaled WebP through the Images binding, never the original. Token cost is quadratic in edge length — roughly (w×h)/750:

inline_max_px	WebP	~image tokens
256	~9 KB	~87
512 (default)	~26 KB	~349
1024	—	~1,400

WebP rather than JPEG because it keeps alpha; a transparent-background image flattens to black through JPEG. Full resolution stays one fetch away at the URL.

Three tiers, not one tool per model. draft | standard | premium maps to model ids internally. Cost across those tiers varies 40×, so the tool descriptions carry arena rankings and per-model strengths, and list_image_models returns the whole table — routing policy lives in data, not in your system prompt.

A budget counter, not a prompt. Agents call image tools in loops. A Durable Object reserves the estimated cost before each call and refunds it if the call fails. Over the cap the tool returns an error instead of an image.

Where a provider reports what it actually charged, the ledger is trued up to the real number — Reve returns credits_used, so those calls bill exactly (cost_is_estimate: false) and the response carries provider_usage including your remaining credit balance. OpenAI and the gateway models bill against the price table, flagged cost_is_estimate: true.

Retries do not double-pay. Identical requests are cached (gateway cacheKey for catalog models) for CACHE_TTL_SECONDS. Pass variation to force a re-roll.

Models

Model	Route	Max res	Edits	~$/image	Notes
openai/gpt-image-1-mini	direct	1024px	16 refs	0.005–0.052	The floor. Not in Cloudflare's catalog.
openai/gpt-image-2	direct	1536px	16 refs	0.005–0.211	#1 Artificial Analysis Image Arena (~1339 Elo, Jul 2026). Best text rendering.
openai/gpt-image-1.5	direct	1792px	16 refs	0.009–0.20	Previous flagship, has style.
google/nano-banana-pro	gateway	4K	3 refs	0.134 / 0.24 (4K)	Native 4K, multi-subject realism.
google/nano-banana-2	gateway	4K	3 refs	0.045–0.15	Best all-round default.
google/nano-banana-2-lite	gateway	2K	3 refs	0.034	Cheap Google drafts.
google/imagen-4	gateway	2K	—	0.02	Bulk text-to-image.
reve/v2	direct	4K	—	0.20 (150 cr)	Layout-first: typography, packaging, posters. Verified 4096×4096.
reve/v1	direct	2K	4 refs	0.024 (18 cr)	Cheapest non-draft option here. Reve's editing surface.

Prices are provider list prices verified July 2026, excluding prompt/input tokens. They drive the budget guardrail; they are not invoices.

Billing paths

Three separate accounts get charged depending on the model:

• gateway — env.AI.run against Cloudflare's unified catalog. Cloudflare holds the provider keys and deducts your Cloudflare credits. BYOK is not supported through the AI binding. Unified Billing charges a 5% fee on credit purchases; inference itself is passed through at provider rates.
• openai — direct to api.openai.com with your own key. Set OPENAI_VIA_GATEWAY=true to move these onto the gateway instead.
• reve — direct to api.reve.com. Reve is not in Cloudflare's catalog. Measured 2026-07-28: /v1/image/create = 18 credits ($0.024), /v2/image/create = 150 credits ($0.20) — an 8× spread between the two endpoints, so which one you route to matters more than the provider choice. Priced at the $10 / 7,500-credit pack; set REVE_USD_PER_CREDIT if yours differs.

Hosting itself is cheap: the Workers Paid plan is $5/mo for 10M requests and 30M CPU-ms; Durable Objects with the SQLite backend run on the free plan too. The image spend is the real cost and is entirely separate.

Run it locally

npm install
cp .dev.vars.example .dev.vars   # add your keys
npm run dev:local                # no Cloudflare account needed

dev:local uses wrangler.local.jsonc, which omits the ai binding — that binding only runs against Cloudflare's edge and forces wrangler dev into remote mode (and a login) just to boot. In this mode the OpenAI and Reve models work fully; google/* returns a clear error. For the Google models:

npx wrangler login
npm run dev                      # full config, AI binding live

Smoke test:

curl -s localhost:8787/health
curl -s -X POST localhost:8787/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -H 'authorization: Bearer <MCP_TOKEN>' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Behind a TLS-intercepting proxy

workerd ships its own CA bundle and ignores NODE_EXTRA_CA_CERTS, so on a network running Netskope/Zscaler every outbound HTTPS fetch from a local Worker fails with an opaque internal error. Run the relay in a second terminal:

npm run relay

and point the providers at it in .dev.vars:

OPENAI_BASE_URL="http://localhost:8788/openai"
REVE_BASE_URL="http://localhost:8788/reve"

Deployed Workers call providers from Cloudflare's edge, so none of this applies in production.

Deploy

npx wrangler r2 bucket create image-mcp-images   # binding: BUCKET
npx wrangler secret put MCP_TOKEN        # any long random string
npx wrangler secret put OPENAI_API_KEY
npx wrangler secret put REVE_API_KEY
npm run deploy

Connect it

Claude Code

claude mcp add --transport http imggen https://<worker>.workers.dev/mcp \
  --header "Authorization: Bearer <MCP_TOKEN>"

claude.ai / Desktop — Settings → Connectors → Add custom connector → paste https://<worker>.workers.dev/mcp, then put Authorization: Bearer <MCP_TOKEN> under Advanced → Request headers.

Auth is a static bearer token, checked with a constant-time compare. That is the right shape for a single-tenant server: the OAuth path (401 + WWW-Authenticate: Bearer resource_metadata=…) would require standing up a full authorization server, and Anthropic does not support pure machine-to-machine client_credentials anyway — every connection needs user consent.

Tools

Tool	What it does
generate_image	Text → image. tier, provider, aspect, resolution, format, transparent, variation, return_inline, inline_max_px.
edit_image	Image(s) + instruction → image. Accepts https URLs or data: URIs.
list_image_models	Full catalog: cost, ranking, limits, what each model is best and worst at.
get_image_budget	Today's spend against the cap.

Configuration

Var	Default	Meaning
MCP_TOKEN	—	Bearer token clients must send. Unset = open server.
OPENAI_API_KEY	—	Enables the OpenAI models.
REVE_API_KEY	—	Enables the Reve models.
DAILY_BUDGET_USD	5	Hard daily cap on estimated spend.
CACHE_TTL_SECONDS	300	Gateway cache TTL / retry-dedupe window.
AI_GATEWAY_ID	default	AI Gateway name for catalog models.
OPENAI_VIA_GATEWAY	—	"true" routes OpenAI through Cloudflare instead.
REVE_USD_PER_CREDIT	0.001333	USD per Reve credit ($10 / 7,500 pack).
PUBLIC_BASE_URL	request origin	Origin used to build returned image URLs.

Verified / unverified

Verified live on 2026-07-28: MCP protocol negotiation (2025-11-25), tool listing, generate_image and edit_image end-to-end against gpt-image-1-mini and reve/v1, R2 persistence, image serving, downscaled WebP previews at 256/512px with alpha intact, budget reserve/refund, and the credit-accurate true-up (an 18-credit Reve call billed as exactly $0.024).

Reve's schema was discovered by probing its validation errors — its reference docs sit behind the API console login — then confirmed against live calls.

Not yet exercised: the gateway transport, which needs a Cloudflare account with credits. Its response shape ({state, result: {image}}) comes from Cloudflare's published model pages.