imagine-mcp

A Model Context Protocol (MCP) server for image generation via the OpenRouter API.

Designed to work with Cline, VS Code GitHub Copilot, and Claude Code. Generate high-quality images directly from your editor and save them into the repository you're currently working in — no copy/paste, no context bloat.

Features

• 4 curated models with clear pricing and best-use cases (from $0.04/image)
• Saves to disk by default into assets/generated-images/ of the current workspace
• Context-friendly: returns only metadata (path, size, media type) unless you explicitly request base64
• Per-model validation: catches unsupported aspect_ratio / resolution / output_format / n before calling the API
• Cost transparency: reports API cost when available, estimates it otherwise
• Retry with backoff for 429 / 5xx / network errors
• Advanced image_config support (custom fonts, scoring rubrics, background color) for models that accept it
• list_generated_images tool so the assistant can reference images already produced
• Configurable default model via env var (cheapest by default)

Available models

Model ID	Name	Best for	Pricing	Max n
bytedance-seed/seedream-4.5	Seedream 4.5	Cheap general use, portraits, small text	$0.04/image (flat)	4
x-ai/grok-imagine-image-quality	Grok Imagine	Photorealism, posters, text in images	from $0.05/image	4
recraft/recraft-v4.1-vector	Recraft v4.1 Vector	Logos, icons, SVG	$0.08/image	1
sourceful/riverflow-v2.5-fast	Riverflow v2.5 Fast	Quick iterations, brand-aligned variations	dynamic	4

For per-model prompting best practices, see docs/model-guides.md.

Prerequisites

• Node.js >= 18
• An OpenRouter API key — get one at https://openrouter.ai/keys

Installation

Option A — Use directly via npx (recommended, no clone needed)

The MCP clients below can launch the server with npx -y imagine-mcp. No local install required.

Option B — Clone & build locally

git clone <your-repo-url> imagine-mcp
cd imagine-mcp
npm install
npm run build

Client setup

The server reads your API key from the OPENROUTER_API_KEY environment variable. All clients below pass it through env.

Cline

Add to cline_mcp_settings.json:

{
  "mcpServers": {
    "imagine-mcp": {
      "command": "npx",
      "args": ["-y", "imagine-mcp"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

VS Code GitHub Copilot

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "imagine-mcp": {
      "command": "npx",
      "args": ["-y", "imagine-mcp"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Claude Code

Add to .mcp.json in your project root (or ~/.mcp.json for global):

{
  "mcpServers": {
    "imagine-mcp": {
      "command": "npx",
      "args": ["-y", "imagine-mcp"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Local build instead of npx

If you cloned the repo, replace the command/args with:

"command": "node",
"args": ["/absolute/path/to/imagine-mcp/build/index.js"]

Environment variables

Variable	Required	Default	Description
OPENROUTER_API_KEY	yes	—	OpenRouter API key
OPENROUTER_IMAGES_DEFAULT_MODEL	no	bytedance-seed/seedream-4.5	Default model when none is specified
OPENROUTER_IMAGES_OUTPUT_DIR	no	<workspace>/assets/generated-images	Default output directory
OPENROUTER_IMAGES_TIMEOUT_MS	no	180000	Per-request timeout (ms)
DEBUG	no	—	Set to imagine-mcp for verbose logs

Tools

generate_image

Generate one or more images from a text prompt.

Required: prompt, model

Common optional parameters:

Parameter	Type	Notes
resolution	512 | 1K | 2K | 4K	Model-dependent
aspect_ratio	1:1 | 16:9 | 9:16 | 4:3 | 3:4 | auto | ...	Model-dependent
size	string	Shorthand: "2K" or "2048x2048"
quality	auto | low | medium | high	Not all models
output_format	png | jpeg | webp | svg	svg only for Recraft
background	auto | transparent | opaque
n	number	1–10 (clamped per model)
save_to_disk	boolean	Default true — saves to assets/generated-images/
return_b64	boolean	Default false. true returns ~1MB+ base64 (use sparingly)
output_dir	string	Override save directory (resolved against workspace root)
filename	string	Base filename without extension
image_config	object	Advanced model-specific options (see list_image_models)

Example (assistant-style call):

{
  "prompt": "Minimalist owl logo, flat vector, geometric shapes, dark navy and gold, no text",
  "model": "recraft/recraft-v4.1-vector",
  "output_format": "svg",
  "save_to_disk": true,
  "filename": "owl_logo"
}

Response (abridged):

{
  "success": true,
  "model": "recraft/recraft-v4.1-vector",
  "images_generated": 1,
  "images": [{ "index": 0, "media_type": "image/svg+xml", "saved_to": "/repo/assets/generated-images/owl_logo.svg" }],
  "saved_to_disk": true,
  "output_dir": "/repo/assets/generated-images",
  "usage": { "cost": 0.08, "cost_source": "api" },
  "pricing_note": "$0.08/image"
}

list_image_models

Returns the full catalog (or a single model) with supported parameters, pricing, best-use cases, and supported image_config fields. Call this first if you're unsure which parameters a model accepts.

save_image

Persist base64 image data you already have to disk. Useful when a previous call used return_b64=true.

list_generated_images

Lists image files previously saved in the output directory (most recent first). Handy for the assistant to reference or open images already generated in the current workspace.

How workspace detection works

On startup the server walks up from its current working directory looking for a project marker (.git, package.json, pubspec.yaml, pyproject.toml, requirements.txt, Cargo.toml, go.mod, .hg, .svn). The first directory containing a marker becomes the workspace root, and images are saved under <workspace root>/assets/generated-images/ by default.

MCP hosts (Cline, Copilot, Claude Code) launch the server with CWD set to the open workspace, so images land in the right repo automatically.

output_dir is resolved against the workspace root and cannot escape it (path traversal is rejected).

Cost transparency

• When OpenRouter returns usage.cost, it is reported as usage.cost with cost_source: "api".
• When the API does not return a cost (e.g. Riverflow dynamic pricing finalizes after completion), the server estimates it from the model's flat price table and reports usage.estimated_cost with cost_source: "estimated".
• The model's pricing_note is always included in the response.

Prompting best practices

Each model responds better to a different prompting style. See docs/model-guides.md for official, per-model guidance:

• Seedream 4.5 — structured [Subject]+[Action]+[Environment]+[Style]+[Technical]+[Text] formula; quote literal text
• Grok Imagine — director-style language; generate 2–3 outputs (no seed); explicit "no additional text" for clean product shots
• Recraft v4.1 Vector — structured vector prompts (graphic type / shape logic / color system / line discipline / constraints); name colors; "no gradients, no shadows"
• Riverflow v2.5 Fast — thinking_level, scoring_prompt + scoring_rubric for brand alignment, font_inputs, background_hex_color

Development

npm install
npm run build      # compiles to build/index.js and sets exec bit
npm start          # runs the server
DEBUG=imagine-mcp npm start   # verbose logs

License

MIT