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 ~/Pictures/imgx/ by default.

2. Output Directory Structure

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.

~/Pictures/imgx/
  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/s-xxxx/

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

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

Output priority:

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.

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.

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" }
    }
  }
}

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" }
    }
  }
}

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 own application directory. To control where images are saved, add "IMGX_OUTPUT_DIR": "C:\\Users\\you\\Pictures" to the env section, or run imgx config set output-dir <path> beforehand.

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-2.5-flash-image",
    "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-2.5-flash-image    # 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-2.5-flash-image",
    "IMGX_OUTPUT_DIR": "./generated-images"
  }
}

7. Provider Comparison

Gemini vs OpenAI

Gemini Model Comparison

When to Use Which

• Gemini: Default provider. Free tier available. Use when you need resolution control
• OpenAI: Use when you need multi-image generation or output format selection
• gemini-3-pro: When high quality matters (cover images, OGP, etc.)
• gemini-2.5-flash: When speed and cost are the priority (drafts, rapid iteration)

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.

Links

• GitHub
• npm
• SOMA COFFEE KYOTO