Image Generation & Editing

Generate and edit images using the imgx MCP tools. Gemini and OpenAI providers supported.

Default model behavior

When the user does not specify a model, use Nano Banana (`gemini-2.5-flash-image`) — the free tier model. This lets users start immediately without paid API access (500 images/day, no credit card).

Suggest upgrading to a paid model when:

• The user is unsatisfied with quality and wants improvement
• The user needs 4K resolution or extended aspect ratios (1:4, 1:8, 4:1, 8:1, 21:9)
• The user needs high text rendering accuracy (→ Nano Banana 2)
• The user explicitly asks for higher quality or a specific paid model
• The task clearly requires maximum quality (e.g. final production assets, print)

When suggesting an upgrade, briefly explain what the paid model adds. Example:

"This was generated with the free model (Nano Banana). For higher resolution (up to 4K) and more aspect ratio options, I can re-generate with Nano Banana 2 or Pro — these require paid API access."

When to use

• User asks to create, generate, or make an image
• User asks to edit, modify, or change an existing image
• User needs a cover image, diagram, icon, or visual asset
• User wants to refine an image iteratively ("make it darker", "change the background")
• User mentions a model by alias (Nano Banana, NB2, etc.) — see Model aliases below

Model aliases

Users may refer to models by their alias. Map these to the correct model parameter value:

When the user says "ナノバナナ2で画像作って" → use generate_image with model="gemini-3.1-flash-image-preview". When the user says "Nano Banana Proで前の画像を作り直して" → use edit_last with model="gemini-3-pro-image-preview". When the user says "ナノバナナで画像作って" or "NB" → use generate_image with model="gemini-2.5-flash-image" (free tier model).

Setup

If the MCP tools (generate_image, edit_image, edit_last, list_providers, undo_edit, redo_edit, edit_history, switch_session, clear_history, set_output_dir) are already available, skip this section.

1. Add MCP server

Add imgx-mcp to the project's .mcp.json (create the file if it doesn't exist):

{
  "mcpServers": {
    "imgx": {
      "command": "npx",
      "args": ["--package=imgx-mcp", "-y", "imgx-mcp"],
      "env": { "GEMINI_API_KEY": "your-key" }
    }
  }
}

On Windows, use "command": "cmd" and prepend "/c" to args:

{
  "mcpServers": {
    "imgx": {
      "command": "cmd",
      "args": ["/c", "npx", "--package=imgx-mcp", "-y", "imgx-mcp"],
      "env": { "GEMINI_API_KEY": "your-key" }
    }
  }
}

After adding, restart Claude Code for the MCP server to connect.

2. API key

Get at least one API key:

• Gemini (default): Google AI Studio
• OpenAI: OpenAI Platform

Set the key in the .mcp.json env section (above), or via CLI:

npx imgx-mcp config set api-key YOUR_KEY --provider gemini

3. Project root (optional but recommended)

imgx-mcp uses the project root to determine where .imgx/ (history + default image output) is created. Without it, images go to ~/Pictures/imgx/ and history to ~/.config/imgx/.

Detection priority: env var > MCP roots > .imgxrc upward search > user config projectRoot.

Claude Code usually auto-detects via MCP roots — no extra config needed. Claude Desktop does not support auto-detection, so set IMGX_PROJECT_ROOT in the env.

#### .imgxrc project config

Create with npx imgx-mcp init or manually. Shared via Git (do not put API keys here):

{
  "defaults": {
    "model": "gemini-2.5-flash-image",
    "outputDir": "./assets/images",
    "aspectRatio": "16:9"
  }
}

#### Claude Desktop config example

{
  "mcpServers": {
    "imgx": {
      "command": "npx",
      "args": ["--package=imgx-mcp", "-y", "imgx-mcp"],
      "env": {
        "GEMINI_API_KEY": "your-key",
        "IMGX_PROJECT_ROOT": "C:\\Users\\you\\my-project"
      }
    }
  }
}

Models and image specs

Nano Banana Pro — gemini-3-pro-image-preview

Google's highest-quality image generation model. Paid only.

Nano Banana 2 — gemini-3.1-flash-image-preview

Fast model with Pro-level capabilities at lower cost. Improved text rendering.

Nano Banana — gemini-2.5-flash-image

The only Gemini image model with a free tier. Best entry point for trying imgx-mcp without cost.

OpenAI models

3 models available. All share the same capabilities (multi-output, format selection). Same API, same parameters.

Model selection guide

Upgrade path: Nano Banana (free) → Nano Banana 2 (fast, affordable paid) → Nano Banana Pro (highest quality paid)

MCP tools

Use these tools directly. No Bash needed.

generate_image

Generate an image from a text prompt.

edit_image

Edit an existing image with text instructions. No mask needed — the model determines what to change from the text.

edit_last

Edit the last generated or edited image. No input path needed — automatically uses the previous output.

list_providers

List available providers and their capabilities. No parameters.

undo_edit

Undo the last edit, reverting to the previous image state. No parameters.

Returns the file path and position of the current entry after undo.

redo_edit

Redo a previously undone edit. No parameters.

Returns the file path and position of the current entry after redo.

edit_history

Show the full edit history with all sessions. No parameters.

Returns all sessions with their entries, including operation type, prompt, provider, file paths, and timestamps.

switch_session

Switch to a different editing session to continue work on a previous image chain.

clear_history

Clear edit history for the current project. Optionally delete image files in managed directories.

set_output_dir

Change the default output directory for generated images.

Practical workflows

Blog cover image

1. generate_image: prompt="A developer's desk with laptop showing terminal, coffee cup, warm morning light" aspect_ratio="16:9"
   (uses free Nano Banana model by default)
2. Review the result with the user
3. edit_last: prompt="Make the color palette warmer" (if user wants changes)
4. If user wants higher quality → re-generate with model="gemini-3-pro-image-preview" resolution="2K"

Iterative refinement

The edit_last tool is the key to conversational image editing. Each call takes the previous output as input:

generate_image -> edit_last -> edit_last -> edit_last -> done

Tell the user what was generated, ask if they want changes, and use edit_last to apply them. This is the most natural workflow.

Undo / redo workflow

Use undo_edit and redo_edit to navigate through edit history:

generate_image -> edit_last -> edit_last -> undo_edit -> undo_edit -> redo_edit

After undo, calling edit_last branches from the current position — abandoned entries and their files are automatically deleted from disk.

Each generate starts a new session. Use edit_history to see all sessions, and switch_session to resume work on a previous image chain. edit_last uses the current position in the switched session.

Comparing providers

Generate the same prompt with different providers to let the user choose:

1. generate_image: prompt="..." provider="gemini"
2. generate_image: prompt="..." provider="openai"
3. Show both results. User picks their preferred version
4. edit_last to refine the chosen one (note: edit_last uses the most recent output)

Icon or logo variations

1. generate_image: prompt="Minimalist coffee bean icon, white background" aspect_ratio="1:1" count=3
   (count works with OpenAI provider only)
2. For Gemini, generate multiple times with slight prompt variations

Common use cases and techniques

When the user describes what they need, suggest appropriate parameters and approach based on context.

Use case: OGP / social share images

• Aspect ratio: 16:9 (Twitter/X, Facebook) or 1.91:1 (use 2:3 as closest)
• Start with Nano Banana (free) for drafting. Upgrade to 2K resolution with Nano Banana 2 or Pro for final
• For text on the image — suggest Nano Banana 2 (best text rendering, paid)
• Prompt tip: Describe the scene plus any text overlay you want rendered directly

Use case: Blog / article cover

• Aspect ratio: 16:9 or 3:2
• Resolution: 2K (balances quality and file size)
• Prompt tip: Describe the main visual concept. Avoid metaphorical descriptions — be literal about what should appear

Use case: Presentation slides

• Aspect ratio: 16:9
• Resolution: 2K
• Use a consistent visual theme across slides (describe the same color palette, style, and composition framing)
• Prompt tip: Include "slide design" or "presentation visual" for cleaner layout

Use case: App store screenshots / product images

• Aspect ratio: 9:16 (portrait), 16:9 (landscape), 1:1 (square)
• Draft with Nano Banana (free), then 4K with Nano Banana 2 or Pro (paid) for retina
• Prompt tip: Describe the device frame and screen content you want shown

Use case: Vertical content (Stories, Reels, Shorts)

• Aspect ratio: 9:16
• Full-bleed imagery works best — describe edge-to-edge scenes

Use case: Ultra-wide banner

• Aspect ratio: 21:9 or 8:1 — requires Gemini 3.x models (paid)
• Good for website hero banners, email headers, panoramic scenes
• Note: Nano Banana (free) does not support extended ratios. Suggest upgrade if user needs these

Use case: Tall / narrow (Pinterest, infographic header)

• Aspect ratio: 1:4 or 1:8 — requires Gemini 3.x models (paid)
• Describe vertical flow — elements stacked top to bottom

Use case: Icons, logos, stickers (transparent background)

• Use OpenAI with background="transparent" and output_format="png" (or webp)
• JPEG does not support transparency — use PNG or WebP
• Aspect ratio: 1:1 for icons
• Prompt tip: Describe only the subject. Do not describe the background — the API handles removal

Use case: WordPress / web content

• Prefer output_format="jpeg" (OpenAI) for smaller file size
• Or generate with Gemini (PNG) and let the CMS handle conversion
• 2K resolution is sufficient for web

Popular editing techniques

When the user wants to modify an image, suggest these proven approaches with edit_last:

Atmosphere and mood

Composition adjustments

Element manipulation

Style transfer

Practical refinement patterns

These multi-step sequences are common in real workflows:

Quality escalation: Start with Nano Banana (free) for drafting. When the concept is right, offer to re-generate with Nano Banana 2 (paid, fast, 4K) or Nano Banana Pro (paid, highest quality) for the final version.

A/B comparison: Generate the same prompt with provider="gemini" then provider="openai" and show both to the user.

Iterative detail building: Start broad ("a coffee shop interior"), then add details step by step ("add plants by the window", "put a barista behind the counter", "add warm overhead lighting").

Style exploration: Generate a base image, then apply different style transfers with edit_last to find the right mood. Use undo_edit to return to the base and try another style.

Viral and trending image styles

Popular AI image styles that users may request. Use these prompt templates with generate_image or edit_last.

When the user requests a trending style, use the appropriate template and adjust based on their subject. Combine with background="transparent" (OpenAI) for stickers.

Specialized use case guides

Icon set generation

Generate multiple icons with consistent style for an app or project:

1. Define the style: "Flat minimalist icon, 2px stroke, rounded corners, single accent color #FF6B35 on white"
2. generate_image: prompt="[style] of a home/house symbol" aspect_ratio="1:1"
3. generate_image: prompt="[style] of a settings gear symbol" aspect_ratio="1:1"
4. generate_image: prompt="[style] of a user profile symbol" aspect_ratio="1:1"

Key: Repeat the exact same style description in every prompt. This is more reliable than using edit_last for style consistency across separate icons.

For transparent icons: Use OpenAI with background="transparent" and describe only the icon subject.

Seamless pattern

1. generate_image: prompt="Seamless tileable pattern of [elements], evenly distributed, no visible seam edges, [style]"
2. edit_last: prompt="Make the pattern more evenly distributed, ensure elements don't cluster at edges"

Tip: Include "seamless tileable pattern" and "no visible seam edges" in the prompt.

Technical diagram / architecture

1. generate_image: prompt="Clean technical architecture diagram showing [components], labeled boxes connected by arrows, white background, minimal style, clear hierarchy"
2. edit_last: prompt="Add a label '[text]' to the top box"

For accurate text labels, use Nano Banana 2 (best text rendering) or OpenAI gpt-image-1.5.

Story sequence (consistent characters)

Maintain visual consistency across a sequence of images:

1. Define a character DNA: "A woman with short dark hair, round glasses, wearing a navy blue cardigan and white t-shirt"
2. generate_image: prompt="[character DNA], sitting at a desk reading a book, warm indoor lighting"
3. generate_image: prompt="[character DNA], standing at a coffee shop counter ordering, morning light through windows"
4. generate_image: prompt="[character DNA], walking on a city street with a tote bag, afternoon sun"

Key: Copy the exact character description into every prompt. Add scene-specific context after the character DNA. Consistency improves when using the same model and provider across all images.

Multi-image consistency techniques

When the user needs multiple images that look like they belong together (slide decks, social media series, brand assets):

Design token approach

Define visual constants and reuse them across all prompts:

Color:     "earth tones, warm browns (#8B6914) and sage green (#87A96B)"
Style:     "flat illustration with subtle paper texture, 2D, no gradients"
Lighting:  "soft diffused natural light, no harsh shadows"
Framing:   "centered subject, 20% padding, clean background"

Prepend these tokens to every prompt: "[tokens], [subject-specific content]"

Character DNA template

For recurring characters or mascots, write a fixed description block:

Character: "A friendly robot with a round head, single blue eye, matte silver body, short stubby arms, standing upright"

Never paraphrase — copy the exact same text each time.

Style reference chain

Use one generated image as the style anchor:

1. generate_image: prompt="[detailed style + first scene]" → establish the look
2. For subsequent images: describe the same style explicitly + new scene content
3. If style drifts: undo_edit back, regenerate with more explicit style description

Consistency tips

• Same model, same provider across all images in a set
• Front-load the style description before scene-specific content
• Use exact phrases — "soft watercolor" not sometimes "watercolor" and sometimes "painted in watercolors"
• Generate at the same resolution — mixing resolutions changes perceived style
• Review and regenerate — if one image in a set drifts, regenerate it rather than trying to edit it to match

Platform size guide

Recommended aspect ratios and resolutions for common platforms. When the user mentions a platform, suggest these settings automatically.

Social media

OGP (Open Graph Protocol)

For OGP images: Use 16:9 at 2K resolution. This covers all major platforms.

App stores

Print and documents

Blog platforms

Writing effective prompts

Structure prompts with three layers: Subject → Context → Style. Each layer adds specificity.

Subject (what)

Name the main subject concretely. Avoid abstract descriptions.

Context (where / when / with what)

Add environment, lighting, and surrounding elements.

Style (how it looks)

Specify the visual treatment.

Complete prompt example

Subject:  A barista pouring steamed milk into a latte, creating a rosetta pattern
Context:  At a wooden counter in a small coffee shop, warm pendant light overhead, coffee equipment in the background
Style:    Close-up shot, shallow depth of field, warm earth tones, natural lighting

→ "A barista pouring steamed milk into a latte creating a rosetta pattern, at a wooden counter in a small coffee shop, warm pendant light overhead, coffee equipment in background, close-up shot, shallow depth of field, warm earth tones, natural lighting"

Prompt tips

• Be literal, not metaphorical — "a bridge connecting two cliffs" not "bridging the gap between ideas"
• Front-load the subject — The model weights the beginning of the prompt more heavily
• Specify what you don't want sparingly — "no text" or "no people" can help, but negative prompts are less reliable than positive descriptions
• For text in images — Put the exact text in quotes: "with the text 'HELLO WORLD' in bold white sans-serif at the top center"
• For editing — Describe only the change, not the entire image. "Make the sky sunset orange" not "A scene with everything the same but the sky is now sunset orange"

Tips

• Be specific in prompts: "A wooden table with a ceramic pour-over dripper, steam rising, soft natural light from left" works better than "coffee scene"
• Use edit_last for iteration: Don't ask the user to specify file paths. Just use edit_last after any generation or edit
• Check provider capabilities: Use list_providers if unsure what a provider supports
• Where `.imgx/` is created: The .imgx/ directory holds both edit history (output-history.json) and default image output. When a project root is detected, it's created at <project-root>/.imgx/. Without a project root, images go to ~/Pictures/imgx/ and history to ~/.config/imgx/. All clients sharing the same project root share the same history. See the Project root setup section above for configuration methods
• Default output: Images save to <project-root>/.imgx/<session-id>/ (project auto-detected). Falls back to ~/Pictures/imgx/ when no project is detected. Use output or output_dir to customize
• Custom output_dir and history: When output_dir is specified on generate_image, the path is recorded as session metadata in output-history.json. edit_last reads this to inherit the output location. Only image files go to the custom path — history always stays in .imgx/ (or global config directory)
• Inline preview: MCP responses include base64 image data for inline display in supported clients
• Undo/redo: Use undo_edit and redo_edit to step through edit history. Each session holds up to 10 entries
• Sessions: Each generate_image starts a new session. Use edit_history to see all sessions and switch_session to resume a previous one
• Sequential naming: When output specifies a filename, edit_last appends sequential numbers: cover.png -> cover-1.png -> cover-2.png. Undo automatically deletes discarded files
• Project scope: History is stored per-project in <project-root>/.imgx/output-history.json. clear_history only affects the current project. Relative paths in output and output_dir are resolved against the project root

CLI fallback

If MCP tools are not available (MCP server not configured), fall back to CLI via Bash:

npx imgx-mcp generate -p "prompt" -o output.png
npx imgx-mcp edit -i input.png -p "edit instruction"
npx imgx-mcp edit --last -p "refine further"

See providers reference for detailed provider capabilities.