# 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](https://runware.ai) — 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](https://my.runware.ai) (pay-per-use, new
   accounts get free credits).
2. Build:

   ```sh
   npm install && npm run build
   ```

3. Register with Claude Code (either way):

   ```sh
   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

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