Image Forge
Uses Cloudflare Workers AI to generate and edit images with FLUX.2 Klein, including quota-aware budgeting and disk output of generated PNG/JPG files.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Image Forgemake a 1024x1024 cover image of a lighthouse at dusk, muted blues"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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_imagefor text,edit_imageto rework an existing file, URL orfile://path.Honest trade-off.
flux-2-klein-4bis 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 .envFill 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 |
|
| Text to image. |
|
| Existing image plus instructions; local 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 |
Prompt shaping, size, variants, quota discipline. | |
Cloning an existing image while changing one named thing, without losing composition or lighting. |
npx skills add JORDANROBERTO74/image-forge-mcpOr 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 |
| — | Required to generate. |
| — | Required to generate. |
|
| Output folder, created if missing. |
|
| Model when a call omits one. |
|
| Cap on |
|
| Max input image size. |
|
| Warning threshold. |
|
| Hard stop before the daily limit. |
|
| Per-request timeout. |
|
| Generation log. |
|
| 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-4bis 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-img2imgis registered for itsstrengthcontrol 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 withIMAGE_FORGE_MULTIPART_IMAGE_FIELDif that changes.Output is written atomically (
.tmpthen 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 toolsedit_imageA
Genera una nueva imagen a partir de otra imagen + un prompt. Guarda el resultado en disco y devuelve la ruta.
| Name | Required | Description | Default |
|---|---|---|---|
| seed | No | Semilla para reproducir el resultado | |
| count | No | Cuántas variantes generar (1-4) | |
| image | Yes | Ruta local, file:// o URL http(s) de la imagen de entrada | |
| model | No | flux-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. | |
| steps | No | Pasos de difusión (1-20) | |
| width | No | Ancho de salida en px (256-2048) | |
| height | No | Alto de salida en px (256-2048) | |
| prompt | Yes | Qué debe mostrar la imagen o qué debe cambiar respecto a la de entrada | |
| out_dir | No | Carpeta destino. Por defecto IMAGE_OUT_DIR o %USERPROFILE%\Downloads | |
| strength | No | 0 = casi idéntica al original, 1 = ignora el original. Solo sd15-img2img; se ignora en flux-2-klein-4b | |
| negative_prompt | No | Elementos que NO deben aparecer (solo sd15-img2img) |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| seed | No | Semilla para reproducir el resultado | |
| count | No | Cuántas variantes generar (1-4) | |
| model | No | flux-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. | |
| steps | No | Pasos de difusión (1-20) | |
| width | No | Ancho de salida en px (256-2048) | |
| height | No | Alto de salida en px (256-2048) | |
| prompt | Yes | Qué debe mostrar la imagen o qué debe cambiar respecto a la de entrada | |
| out_dir | No | Carpeta destino. Por defecto IMAGE_OUT_DIR o %USERPROFILE%\Downloads | |
| negative_prompt | No | Elementos que NO deben aparecer (solo sd15-img2img) |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Ruta local o file:// de la imagen |
TDQS
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.
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.
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.
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.
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.
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.
3 tool updates
v1.0.0- First observed
edit_image - First observed
generate_image - First observed
get_image_info
TDQS
Scored across 3 tools
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.
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.
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.
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
Related MCP Connectors
AI image + video generation for agents: --flag prompt DSL, async generate/poll, x402 pay-per-use.
LLM chat, text tools, image generation, editing, batch image jobs, and asynchronous video generation
Image & PDF tools for AI agents: compress, convert, resize, PDF, AI vision, pipeline.
Generate images, video, and audio with Glif's media-generation agent
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides AI agents and coding assistants with image generation and editing capabilities using OpenAI's GPT-image-1 model, with support for local or Supabase storage.43 PyPI3MIT
- AlicenseNot gradedqualityDmaintenanceEnables Claude Code agents to generate images via the Runware API with full parameter control, exact USD cost reporting, local image saving, and a live gallery.MIT
- AlicenseAqualityAmaintenanceEnables coding agents to generate and edit images using Gemini and OpenAI image models, saving files directly into the project with configurable providers, models, and security restrictions.301MIT
- AlicenseNot gradedqualityCmaintenanceEnables generating and editing images with OpenAI's gpt-image-2 directly from Claude or ChatGPT, including uploads, masks, composition, listing, deletion, and spend tracking through a self-hosted Cloudflare Workers connector.MIT