Skip to main content
Glama
Oriolshhh

runware-image-mcp

by Oriolshhh
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

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).

Related MCP server: SeeDream MCP Server

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).

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers