1. Quick Start

Step 1: MCP Configuration

Add the following to .mcp.json in your project root.

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

On Windows: Change "command" to "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" }
    }
  }
}

Step 2: Get an API Key

You need an API key from at least one provider.

Set the key in the env section of .mcp.json. Alternatively, configure it via the CLI.

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

Keys are stored in ~/.config/imgx/config.json (Linux/macOS) or %APPDATA%\imgx\config.json (Windows).

Step 3: Generate Your First Image

Once configured, just ask the AI to generate an image.

"Generate an image of a coffee cup"

The AI calls the generate_image tool and returns a file path. Compatible clients also display the image inline.

Generated images are saved to <project-root>/.imgx/ when used via MCP (project auto-detected). Falls back to ~/Pictures/imgx/ when no project is detected.

2. Output Directory Structure

Where .imgx/ is Created

The .imgx/ directory holds both edit history (output-history.json) and default image output. Its location is determined by project root detection:

Project root detection is described in Project Scope. All clients that resolve to the same project root share the same .imgx/ directory and history.

Session-Based Directories

Each generate_image call creates a new session with its own directory. Subsequent edit_last calls within the same session save to the same directory.

<project-root>/.imgx/              ← Created at project root
  output-history.json              ← Project-scoped history
  s-a1b2c3d4/                      ← Session 1 (generate → edit → edit)
    imgx-001.png
    imgx-002.png
    imgx-003.png
  s-9f8e7d6c/                      ← Session 2 (generate → edit)
    imgx-004.png
    imgx-005.png

Files from different image chains never mix — each session gets its own directory.

Customizing Output Location

Use the output_dir parameter on generate_image to set the session’s output directory. edit_last inherits this automatically.

You: "Generate a cover image and save it to ./content/images"
→ generate_image: output_dir="./content/images"
→ edit_last also saves to ./content/images/

The specified output_dir is saved as session metadata in output-history.json. This is how edit_last knows where to save — it reads the session’s outputDir from history. The history file itself always stays in .imgx/ (or the global config directory); only the image files go to the custom output location.

<project-root>/.imgx/
  output-history.json    ← History stays here (records session output paths)

./content/images/        ← Images go here (specified via output_dir)
  cover.png
  cover-1.png

For project-wide defaults, create an .imgxrc file:

{
  "defaults": {
    "outputDir": "./assets/images"
  }
}

Output priority (image files only — history location is always determined by project root):

4. Practical Workflows

The key feature of imgx-mcp is that everything — from image generation to the finished result — happens inside an AI conversation. The AI retains context throughout: the article content, project goals, and editing decisions made so far. Users don’t write prompts directly. They describe what they need in natural language.

Every example below works by simply telling the AI what you want.

Creating a Blog Cover Image

You’re writing an article and need a cover image. The AI already knows the article content.

You: "I need a cover image for this article. 16:9 aspect ratio.
      Use your judgment based on the content."

AI:  (Determines from the article that "a developer's morning desk
      with terminal and coffee" fits the theme)
     → Calls generate_image

You: "Nice. Make the colors a bit warmer."

AI:  → Calls edit_last

You: "Looking good. Add a subtle vignette and let's call it done."

AI:  → Calls edit_last, returns the final image path

You just say “warmer colors” — the AI handles the prompt language, service-specific parameters, and file management.

Saving to a Specific Location

When you want images saved directly to your project’s assets directory.

You: "Generate an OGP image and save it to ./content/images.
      Around 1200x630."

AI:  → Calls generate_image with output_dir="./content/images",
        aspect_ratio="2:3"

You: "Simplify the background so the text stands out more."

AI:  → Calls edit_last (saves to the same ./content/images directory)

edit_last inherits the output directory from the generation step. No need to specify the save location again.

Undoing Edits to Try a Different Direction

When three edits in, the result doesn’t match your intent. Go back to an earlier state and try something else.

You: "Create an image of a coffee shop interior."

AI:  → Calls generate_image

You: "Make the lighting warmer."        → edit_last (1st edit)
You: "Add a customer by the window."     → edit_last (2nd edit)
You: "The person looks off. Go back to the warm lighting version."

AI:  → Calls undo_edit (reverts to after the 1st edit)

You: "Instead of a person, add rain outside the window."

AI:  → Calls edit_last (branches from the undo point)

Calling edit_last after undo starts a new branch. The original edits aren’t lost — you can redo to get them back.

Working on Multiple Images in Parallel

Switching between a cover image and an OGP image within the same session.

You: "Let's start with the blog cover image. 16:9."

AI:  → Calls generate_image (session s-aaa created)

You: "Adjust the colors." → edit_last
You: "I also need an OGP image. 1200x630, with a composition
      that highlights the title."

AI:  → Calls generate_image (session s-bbb created)

You: "OGP looks good. Go back to the cover image and brighten it up."

AI:  → Calls switch_session to s-aaa
     → Calls edit_last (continues editing the cover image)

Use edit_history to see all sessions and what was tried in each one.

Comparing Providers

The AI can choose the right provider based on context, or you can request a specific comparison.

You: "Try generating this with both Gemini and OpenAI so I can compare."

AI:  → Calls generate_image with provider="gemini"
     → Calls generate_image with provider="openai"
     → Shows both results

You: "Gemini's is better. Refine that one."

AI:  → Calls switch_session to the Gemini session
     → Calls edit_last

You: "Generate 4 icon variations."

AI:  → Calls generate_image with provider="openai", count=4
     (OpenAI supports multi-image generation)

Using the Finished Image Immediately

Generated images are saved as files, so they’re available for use right after creation.

You: "Set the cover image path in the article's front matter."

AI:  (Already knows the path: ./content/images/s-aaa/imgx-003.png)
     → Updates the front matter

The AI handles the full pipeline — from image generation to embedding it in your content — within the same conversation. No manual file management needed because the context never breaks.

The OGP images and diagrams on this page were themselves produced by imgx-mcp during the content creation session — prompt generation, image creation, iterative editing, and embedding were all handled as a continuous flow.

5. Configuration by Environment

Add imgx-mcp to your tool's MCP configuration file. The structure is the same across all tools.

Claude Code

.mcp.json in your project root:

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

Only include keys for the providers you use.

Skill — letting the AI handle image workflow decisions

The MCP server gives the AI the ability to generate and edit images. The Skill adds the knowledge of how to use those tools well.

With the Skill installed, users don’t need to know image service specifications or how to write effective prompts. Provider-specific capabilities, aspect ratio options, iterative editing strategies, undo/redo workflows — the AI reads this knowledge from the Skill and makes optimal decisions automatically.

You just say “I need a cover image here.” The AI handles the rest.

What the Skill brings:

• Automatic prompt construction — Say “I need a cover image.” The AI builds a structured prompt using the Subject-Context-Style framework: what to show, where to place it, how it should look
• 24 editing techniques — Atmosphere adjustment, composition changes, element manipulation, style transfer. “Make it warmer” or “add depth of field” — the AI selects the right instruction for the model
• Intelligent model selection — Starts with the free model. Suggests paid upgrades only when your needs exceed free tier capabilities, and explains what changes
• Platform-aware sizing — “Twitter OGP” or “App Store screenshot” — the AI picks the correct aspect ratio and resolution. Covers social media, OGP, app stores, print, and blog platforms
• Trending style templates — Ghibli, action figure in box, 3D clay, pixel art, chibi, and more. Name the style and the AI applies the right prompt structure
• Multi-image consistency — Design tokens and character DNA templates maintain visual coherence across slide decks, social media series, and brand assets

The image generation models already have these capabilities. The Skill is what makes them accessible without specialized knowledge.

Skills were first introduced in Claude Code, but the pattern — AI tools loading domain knowledge from reference files — is spreading rapidly across the ecosystem. imgx-mcp’s Skill files can also be used as custom prompts in other environments.

Installation (Claude Code):

# Fetch from GitHub
curl -sL https://raw.githubusercontent.com/somacoffeekyoto/imgx-mcp/main/skills/image-generation/SKILL.md \
  -o .claude/skills/image-generation/SKILL.md --create-dirs
curl -sL https://raw.githubusercontent.com/somacoffeekyoto/imgx-mcp/main/skills/image-generation/references/providers.md \
  -o .claude/skills/image-generation/references/providers.md --create-dirs

your-project/
  .mcp.json                              ← MCP server config
  .claude/
    skills/
      image-generation/
        SKILL.md                         ← Skill body
        references/
          providers.md                   ← Provider reference

Personal skill (all projects): Place in ~/.claude/skills/ instead.

MCP server and Skill roles:

Recommended: Set up both the MCP server + Skill.

One-step install via Plugin: In Claude Code, run /plugin install imgx-mcp to set up the MCP server and Skill together.

Gemini CLI

~/.gemini/settings.json:

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

Claude Desktop

claude_desktop_config.json:

macOS / Linux:

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

Windows:

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

IMGX_PROJECT_ROOT — Set to your project path (e.g. "/Users/you/my-project") to save images and history inside the project. Leave empty to use the global default.

Config file locations:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Restart Claude Desktop after editing.

Note: Claude Desktop runs MCP servers from its application directory, so auto-detection does not work. Set "IMGX_PROJECT_ROOT": "/path/to/project" in the env section above, or run imgx config set project-root /path/to/project in a terminal. See Project Scope for details.

Skill (Claude Desktop)

Claude Desktop also supports Skills via ZIP upload.

1. Download image-generation-skill.zip from the GitHub repository or from the npm package under dist/
2. In Claude Desktop: Settings > Profile > Customize > Skills > Add Skill
3. Upload the ZIP

To update the skill after a new release, re-download and re-upload the ZIP.

Codex CLI

.codex/config.toml:

[mcp_servers.imgx]
command = "npx"
args = ["--package=imgx-mcp", "-y", "imgx-mcp"]
env = { GEMINI_API_KEY = "your-key", OPENAI_API_KEY = "your-key" }

Other Tools (Cursor, Windsurf, etc.)

The same npx pattern works with Cursor, Windsurf, Continue.dev, Cline, Zed, and other MCP-compatible tools. On Windows, use cmd /c npx instead of npx.

6. Configuration Management

imgx-mcp settings are resolved through 5 layers, with higher layers taking priority.

Project Config (.imgxrc)

Place an .imgxrc file in your project root to set project-specific defaults.

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

.imgxrc can be committed to Git for team sharing. Do not put API keys in .imgxrc — use user config or environment variables instead.

User Config

Manage settings with the imgx config command.

imgx config set model gemini-3.1-flash-image-preview    # Change default model
imgx config set output-dir ./images              # Change output directory
imgx config set aspect-ratio 16:9                # Change aspect ratio
imgx config list                                 # Show all settings
imgx config path                                 # Show config file location

Environment Variables in MCP

Pass environment variables through the env section of .mcp.json.

{
  "env": {
    "GEMINI_API_KEY": "your-key",
    "IMGX_MODEL": "gemini-3.1-flash-image-preview",
    "IMGX_OUTPUT_DIR": "./generated-images"
  }
}

7. Provider Comparison

Gemini vs OpenAI

Gemini Model Comparison

When to Use Which

• Nano Banana (gemini-2.5-flash-image): Default. Free tier, no credit card required. Good for getting started and general use
• Nano Banana 2 (gemini-3.1-flash-image-preview): Upgrade for 4K resolution, 14 aspect ratios. Good balance of speed and quality
• Nano Banana Pro (gemini-3-pro-image-preview): Highest quality. Use when it matters (cover images, OGP, etc.)
• OpenAI gpt-image-1: Full-featured. Multi-image generation, format selection, background transparency, quality control
• OpenAI gpt-image-1.5: ~4x faster, 20% cheaper than gpt-image-1, improved text rendering
• OpenAI gpt-image-1-mini: Budget model at $0.005–$0.036/image

8. CLI (Supplementary)

imgx-mcp is primarily used as an MCP server, but it also works as a standalone command-line tool.

Installation

npm install -g imgx-mcp

Requires Node.js 18 or later.

Basic Commands

# Generate an image
imgx generate -p "Coffee cup on a wooden table, morning light" -o output.png

# Edit an image
imgx edit -i photo.png -p "Change the background to a sunset" -o edited.png

# Iterative editing (--last uses the previous output as input)
imgx edit -i photo.png -p "Darken the background"
imgx edit --last -p "Add warm lighting"
imgx edit --last -p "Crop to 16:9" -o final.png

# Undo / redo
imgx undo               # Undo the last edit
imgx redo               # Redo an undone edit

# History management
imgx history            # List all sessions and entries
imgx history switch <session-id>  # Switch session
imgx history clear      # Clear all history (interactive)
imgx history clear --yes          # Clear without confirmation
imgx history clear --keep-files   # Keep image files

# Check providers
imgx providers

Key Flags

For full details, see the README.