runware-image-mcp — Runware image generation for Claude agents

A self-hosted MCP server that lets Claude Code agents generate images directly via the Runware API — full parameter control, exact per-image USD cost reporting, every image saved locally, and a live localhost gallery to browse everything your agents create.

Typical cost: $0.0013/image (FLUX.1 schnell) to $0.0038/image (FLUX.1 dev, the default) at 1024×1024 — versus ~$0.50/image on hosted image-MCP subscriptions.

Setup (3 commands)

1. Get an API key at my.runware.ai (pay-per-use, new accounts get free credits).

2. Build:

   npm install && npm run build
   

3. Register with Claude Code (either way):

   claude mcp add runware -e RUNWARE_API_KEY=<your-key> -- node "$PWD/dist/index.js"
   

   …or copy .mcp.json.example to .mcp.json in your project and fill in the absolute path + key. Restart your Claude Code session afterwards.

The gallery is then live at http://127.0.0.1:7788 while any session with the server is open.

Runtime dependencies are kept minimal: the MCP SDK, zod, and sharp (for local resize_image; ships prebuilt binaries, so npm install needs no build tools on macOS/Linux/Windows).

Tools

Tool	What it does
generate_image	Text→image (and img2img / inpainting) with any Runware model. Params: prompt, negative_prompt, model (AIR id), width/height or aspect_ratio (e.g. "16:9"), steps, cfg_scale, scheduler, seed, number_results, lora, seed_image + strength, mask_image, output_format, output_quality, vae, clip_skip, check_nsfw, return_image, extra_params (raw Runware passthrough). Returns local file path, seed, and exact USD cost.
search_models	Search Runware's 30k+ model catalog; returns AIR ids plus recommended defaults and trigger words.
upscale_image	AI upscale 2–4× via Runware (local path, URL, or previous imageUUID). Costs money; enhances detail.
resize_image	Resize a local image to exact pixel dimensions — local, instant, free (no API call). Exact icon sizes, @1x/@2x retina pairs, precise widths, PNG→WEBP conversion; preserves transparency; contain/cover/fill/inside/outside fit modes. For AI quality enlargement use upscale_image.
remove_background	Background removal (result is PNG with alpha).
list_generated_images	Query the local generation history (prompt/model/project/date filters).

Dimensions are auto-adjusted to Runware's grid (multiples of 64 within 128–2048) and the response tells you when that happened. Seeds are always returned so agents can reproduce or vary a result.

Gallery

• Live grid of all generations (newest first) with prompt, model, seed, cost, and a running total spend; updates automatically as agents generate.
• Lightbox with copy-prompt / copy-seed buttons; filter by prompt text, model, or the project the image was generated from; failures view.
• Binds 127.0.0.1 only (not configurable), Host-header allowlisted, CSP'd.
• Multiple concurrent Claude sessions share one gallery: the first instance owns the port, all instances write to the same image dir.

Configuration (env vars)

Var	Default	Purpose
RUNWARE_API_KEY	—	Required for generation; without it, tools return setup instructions
IMAGE_GEN_DIR	~/.image-gen-mcp	Images + manifest location (shared across sessions)
GALLERY_PORT	7788	Gallery port
GALLERY	on	off disables the gallery
DEFAULT_MODEL	runware:101@1 (FLUX.1 dev)	Model when the agent doesn't pick one
MAX_RESULTS_PER_CALL	4	Cap on number_results
IMAGE_GEN_ALLOWED_DIRS	—	Extra colon-separated dirs allowed as local seed_image sources
RUNWARE_TIMEOUT_MS	120000	API request timeout
RUNWARE_CDN_HOST_SUFFIX	.runware.ai	Download host pin

Privacy & security notes

• ~/.image-gen-mcp/manifest.jsonl and the images are plaintext on disk (dir 0700, files 0600); prompts may contain project context.
• The only outbound connections are api.runware.ai and the Runware CDN. No telemetry.
• Local seed_image files must be real images (extension + magic bytes) inside allowlisted directories — a prompt-injected agent can't feed ~/.ssh/id_rsa to the API.
• The API key lives only in your MCP registration (.mcp.json is gitignored here); it is never logged, stored in the manifest, or shown in the gallery.

Development

npm run build       # tsc + copy gallery assets (run before tests)
npm run typecheck
npm run test        # offline suite — no network, no key, no spend
npm run test:live   # opt-in real-API smoke (~$0.003, needs a key)

Tests cover the Runware client (retry/error mapping/contract drift), storage crash-consistency, path-safety guards, the gallery's HTTP surface, an in-memory MCP protocol round-trip, and stdio purity (nothing but JSON-RPC may touch stdout).