Skip to main content
Glama

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.

Related MCP server: runware-image-mcp

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.

Available Tools

3 tools
edit_imageA

Genera una nueva imagen a partir de otra imagen + un prompt. Guarda el resultado en disco y devuelve la ruta.

NameRequiredDescriptionDefault
seedNoSemilla para reproducir el resultado
countNoCuántas variantes generar (1-4)
imageYesRuta local, file:// o URL http(s) de la imagen de entrada
modelNoflux-2-klein-4b (por defecto): edición por prompt, ~126 neurons/imagen 1024px. sd15-img2img: alternativa con 'strength', pero requiere que tu cuenta tenga acceso habilitado.
stepsNoPasos de difusión (1-20)
widthNoAncho de salida en px (256-2048)
heightNoAlto de salida en px (256-2048)
promptYesQué debe mostrar la imagen o qué debe cambiar respecto a la de entrada
out_dirNoCarpeta destino. Por defecto IMAGE_OUT_DIR o %USERPROFILE%\Downloads
strengthNo0 = casi idéntica al original, 1 = ignora el original. Solo sd15-img2img; se ignora en flux-2-klein-4b
negative_promptNoElementos que NO deben aparecer (solo sd15-img2img)

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden, and it does disclose the key side effect: the result is written to disk and the path is returned. It omits other relevant traits such as cost/neuron consumption, whether files can be overwritten in out_dir, or that most parameters only apply to one of the two models — though the schema covers the latter.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, zero waste, with the input→output contract and the disk-write side effect front-loaded. Nothing in it is redundant with the title or schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter image-editing tool with no annotations and no output schema, the description covers what it does and where the result goes, which is the minimum an agent needs. It does not explain model selection trade-offs or output naming, leaving that entirely to the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and individual parameters (seed, count, model, strength, out_dir, etc.) are well documented in the schema itself. The description adds no meaning beyond that, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource pair ('Genera una nueva imagen a partir de otra imagen + un prompt') and adds the observable outcome (guarda en disco, devuelve la ruta). The 'a partir de otra imagen' phrasing implicitly separates it from generate_image, but the sibling is never named, so the differentiation is left to inference.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: an agent can infer this is the tool to pick when it has a source image, but the description never says when to prefer it over generate_image, nor states prerequisites (accessible input path/URL, model access). No exclusions or alternatives are named.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_imageA

Genera una imagen desde texto. Guarda el resultado en disco y devuelve la ruta.

NameRequiredDescriptionDefault
seedNoSemilla para reproducir el resultado
countNoCuántas variantes generar (1-4)
modelNoflux-2-klein-4b (por defecto): edición por prompt, ~126 neurons/imagen 1024px. sd15-img2img: alternativa con 'strength', pero requiere que tu cuenta tenga acceso habilitado.
stepsNoPasos de difusión (1-20)
widthNoAncho de salida en px (256-2048)
heightNoAlto de salida en px (256-2048)
promptYesQué debe mostrar la imagen o qué debe cambiar respecto a la de entrada
out_dirNoCarpeta destino. Por defecto IMAGE_OUT_DIR o %USERPROFILE%\Downloads
negative_promptNoElementos que NO deben aparecer (solo sd15-img2img)

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It usefully discloses two side effects—saving the result to disk and returning the path—but omits details such as overwrite behavior, permissions, cost implications, and how multiple generated variants affect the returned path.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the core action and followed by the important side effect and return value. There is no wasted language.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The rich schema covers all parameters, and the description minimally covers the lack of an output schema by stating that a path is returned. However, it does not clarify the return format when count is greater than 1, nor does it fully address disk-write behavior for a generation tool with nine parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all nine parameters are already documented in the schema. The description adds no parameter-level meaning beyond 'from text', making the baseline score of 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb and resource: generates an image from text. It does not, however, distinguish this tool from the sibling edit_image, so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'desde texto' implies a text-to-image generation use case and weakly distinguishes it from edit_image, but there is no explicit guidance on when to use this versus edit_image or get_image_info, and no exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_image_infoA

Lee dimensiones, formato y tamaño de un archivo de imagen local. No consume API ni cuota.

NameRequiredDescriptionDefault
pathYesRuta local o file:// de la imagen

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden; it usefully discloses that no API calls or quota are consumed, which confirms a safe local read. However, it omits error behavior for missing/inaccessible paths and does not explicitly frame the operation as read-only and side-effect free.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, zero filler, with the capability stated first and the cost/constraint note second. Nothing could be removed without losing information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter local read tool with no output schema, the description names the returned values (dimensions, format, size) and the no-quota trait, which covers nearly everything an agent needs. Only minor gaps remain around failure modes.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% ('Ruta local o file:// de la imagen'), so the single path parameter is already well documented. The description adds no format examples or path-handling nuances beyond the schema, making baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Lee dimensiones, formato y tamaño de un archivo de imagen local') with three named return fields, so the agent knows exactly what comes back. It does not explicitly contrast with siblings edit_image/generate_image, but the read-only inspection framing makes the difference evident in practice.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The qualifier 'local' plus 'No consume API ni cuota' implies the correct context (local files, free to call), but it never states when to prefer this over edit_image or generate_image, nor any prerequisites such as file existence or permissions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.0.0
    • First observededit_image
    • First observedgenerate_image
    • First observedget_image_info

TDQS

A3.7/5.0

Scored across 3 tools

Disambiguation5/5

Each tool targets a clearly distinct operation: text-to-image (generate_image), image+prompt-to-image (edit_image), and local metadata inspection (get_image_info). There is no plausible overlap; the descriptions explicitly contrast the source of input (text vs. existing image) and note that get_image_info consumes no API quota, further separating it.

Naming Consistency5/5

All three names follow a strict verb_noun snake_case pattern (edit_image, generate_image, get_image_info), with verbs that accurately match the action. No camelCase mixing or vague verbs.

Tool Count4/5

Three tools is a small but coherent surface for an image generation server — one per core action (generate, edit, inspect). It is slightly thin (no listing, batch, or transform operations), but nothing feels redundant or unearned.

Completeness3/5

The generate/edit/inspect cycle covers the primary workflow, but common adjacent operations are absent: resize/crop/convert, upscaling or variations, inpainting with masks, and any way to list or clean up previously written files. An agent can produce and inspect images but hits dead ends for post-processing or asset management.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers