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)

Related MCP server: MCP Image Generator

Available models

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

Tools

generate_image

Generate one or more images from a text prompt.

Required: prompt, model

Common optional parameters:

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