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: Runware MCP Server

Tools

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)

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