image-forge-mcp

Image Forge

An MCP server that lets your coding agent generate or edit images on Cloudflare Workers AI and save them to disk, keeping base64 out of the conversation.

It runs on Cloudflare's free daily allowance, so an agent can draw without a paid API key.

Why this one

• No card, no per-image bill. Cloudflare gives 10,000 Neurons/day free. At roughly 104–126 Neurons per 1024px image, that is about 80 images a day, resetting at 00:00 UTC.
• Files, not payloads. Every call writes a PNG/JPG to disk and returns its path, size and seed. Your context window never absorbs an image.
• A budget guard, not a surprise invoice. Each call is estimated before it runs; the server warns at 8,000 Neurons and refuses to cross 9,500.
• One tool surface for both directions. generate_image for text, edit_image to rework an existing file, URL or file:// path.
• Honest trade-off. flux-2-klein-4b is fast and cheap, not a frontier image model: it handles style, palette and composition well, and struggles with long legible text. There is no mask-based inpainting and no upscaling.

Alternatives such as the OpenAI or Gemini image MCP servers buy stronger instruction following and text rendering, paid per image with an API key. Pick those when that is the requirement; pick this when you want many images a day for free and the results stored on disk.

Quickstart

Requires Node.js >= 20.6 (the server uses --env-file).

git clone https://github.com/JORDANROBERTO74/image-forge-mcp.git
cd image-forge-mcp
pnpm install && pnpm build
cp .env.example .env

Fill two values in .env:

• CLOUDFLARE_ACCOUNT_ID — right sidebar of Workers & Pages in the Cloudflare dashboard.
• CLOUDFLARE_API_TOKEN — a custom token with permission Account → Workers AI → Read.

Then register the server with absolute paths. OpenCode (~/.config/opencode/opencode.jsonc):

"image-forge": {
  "type": "local",
  "command": [
    "node",
    "--env-file=/absolute/path/to/image-forge-mcp/.env",
    "/absolute/path/to/image-forge-mcp/build/index.js"
  ]
}

Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json on Windows):

"image-forge": {
  "command": "node",
  "args": [
    "--env-file=/absolute/path/to/image-forge-mcp/.env",
    "/absolute/path/to/image-forge-mcp/build/index.js"
  ]
}

Use double backslashes for Windows paths inside JSON (C:\\tools\\image-forge-mcp\\...).

Use it

Ask your agent in plain language: "generate a 1024x1024 cover image of a lighthouse at dusk, muted blues". It calls:

{ "prompt": "a lighthouse at dusk, muted blue palette, soft haze", "width": 1024, "height": 1024 }

and gets back a path plus metadata:

✅ 1 imagen(es) · flux-2-klein-4b · 1024x1024
1. /home/you/Downloads/image-forge-20261029-101500.png (1024x1024, 581 KB, seed n/a)
costo: ~104 neurons (hoy: ~104 de ~10.000)

For a variant, the agent calls edit_image with the original path and a prompt that describes what to keep and what to change. Reusing the seed reproduces an earlier result.

Tools

Tool	Input	Use
generate_image	prompt	Text to image.
edit_image	image + prompt	Existing image plus instructions; local path, file:// or http(s)://.
get_image_info	path	Dimensions, format, size. Reads headers only; no API call, no quota.

Shared parameters: model, width/height (256–2048), steps (1–20), seed, count (1–4, each image uses seed + index), out_dir. strength and negative_prompt exist but only affect sd15-img2img, which most accounts cannot access — see Limits.

Skills

Two Agent Skills are included so an agent knows how to drive the server without being told the parameters:

Skill	What it encodes
image-forge-create	Prompt shaping, size, variants, quota discipline.
image-forge-variant	Cloning an existing image while changing one named thing, without losing composition or lighting.

npx skills add JORDANROBERTO74/image-forge-mcp

Or copy them yourself: cp -r skills/* ~/.config/opencode/skills/ (or ~/.claude/skills/ for Claude-compatible agents), then restart the client.

Configuration

Set in .env. Defaults work for a first run.

Variable	Default	Purpose
CLOUDFLARE_ACCOUNT_ID	—	Required to generate.
CLOUDFLARE_API_TOKEN	—	Required to generate.
IMAGE_OUT_DIR	~/Downloads	Output folder, created if missing.
IMAGE_FORGE_DEFAULT_MODEL	flux-2-klein-4b	Model when a call omits one.
IMAGE_FORGE_MAX_IMAGES_PER_CALL	4	Cap on count.
IMAGE_FORGE_MAX_INPUT_MB	10	Max input image size.
IMAGE_FORGE_WARN_NEURONS	8000	Warning threshold.
IMAGE_FORGE_HARD_NEURONS	9500	Hard stop before the daily limit.
IMAGE_FORGE_TIMEOUT_MS	90000	Per-request timeout.
IMAGE_FORGE_HISTORY	~/.image-forge/history.jsonl	Generation log.
IMAGE_FORGE_MULTIPART_IMAGE_FIELD	input_image	Multipart field name for FLUX.2.

Limits and status

Version 1.0.0, single maintainer. Built and tested on Windows with Node 24; no npm package yet, install from source. Expectations are set by what the source and the live API show, not by a roadmap.

• flux-2-klein-4b is the only dependable model here. It is verified for editing (10.5 s at 1024x1024, ~580 KB PNG) and text-to-image (20.7 s) against the live API on 2026-10-22.
• sd15-img2img is registered for its strength control and $0.00 steps, but returned HTTP 403 / error 5018 ("account is not allowed to access") on the test account and cannot do text-to-image at all. Treat it as unavailable unless your account says otherwise.
• Cloudflare does not itemise the multipart schema for FLUX.2; the verified field name is input_image, override with IMAGE_FORGE_MULTIPART_IMAGE_FIELD if that changes.
• Output is written atomically (.tmp then rename); partial files are never left behind.
• Tool output and error messages are in Spanish; the tool names and parameters are English.
• One provider today. Adding another means one file under src/providers/; the tool surface stays the same.

Development commands: pnpm test:local (image I/O, naming, history, budget math) and pnpm test:mcp (handshake, tool list, error paths) run without credentials. pnpm spike reports which models your account can actually reach.

License

MIT. See LICENSE.