imgx-mcp

AI image generation and editing MCP server. Works with Claude Code, Gemini CLI, Cursor, Windsurf, and any MCP-compatible tool.

Generate images from text, edit existing images with text instructions, iterate on results — all from your AI coding environment.

- No prompt engineering— Your AI agent keeps conversation context and auto-constructs optimized prompts. Say what you need; the agent handles prompt structure, model selection, and platform-specific sizing
- 24 editing techniques built in— Atmosphere, composition, style transfer, element manipulation, and trending styles — bundled as a Skill your agent applies on demand
- Session management with undo/redo— Edit iteratively, step back to any point, branch off, or switch between parallel sessions — version control for images

Add to your tool's MCP config (.mcp.json,settings.json, etc.):

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

That's it. Your AI agent can now generate and edit images.

Windows: Replace"command": "npx"with"command": "cmd"and prepend"/c"to the args array.

For Claude Code users, imgx-mcp includes animage-generationskill — a guided prompt that teaches Claude how to use the MCP tools effectively. With the skill installed, type/image-generationto start a guided workflow.

Copy the skill directory from the npm package or GitHub repository to your project:

# From npm (after npx has cached the package) cp -r $(npm root -g)/imgx-mcp/skills .claude/skills # Or from the GitHub repository 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 (Quick start above) .claude/ skills/ image-generation/ SKILL.md ← skill prompt references/ providers.md ← provider reference

The skill files are included in thenpm packageunderskills/and in theGitHub repository.

Claude Desktop supports skills via ZIP upload:
- Downloadimage-generation-skill.zipfrom the repository (or find it in thenpm packageunderdist/)
- In Claude Desktop:Settings > Profile > Customize > Skills > Add Skill
- Upload the ZIP

"Generate a coffee shop interior" → generate_image "Make the lighting warmer" → edit_last "Add a person reading a book" → edit_last

generate → edit_last → edit_last → edit_last ↑ current ← undo_edit ↑ current redo_edit → ↑ current

generate_image → cover.png edit_last → cover-1.png edit_last → cover-2.png generate_image (no output) → imgx-a1b2c3d4.png edit_last → imgx-a1b2c3d4-1.png

Gemini— get a key fromGoogle AI Studio(free tier available forgemini-2.5-flash-image):

imgx config set api-key YOUR_GEMINI_API_KEY --provider gemini

OpenAI— get a key fromOpenAI Platform:

imgx config set api-key YOUR_OPENAI_API_KEY --provider openai

export GEMINI_API_KEY="your-api-key" export OPENAI_API_KEY="your-api-key"

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

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

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

{ "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 to save images inside the project (e.g."C:\\Users\\you\\my-project"). Leave empty to use the global default (~/Pictures/imgx).

Config file location:%APPDATA%\Claude\claude_desktop_config.json(Windows) or~/Library/Application Support/Claude/claude_desktop_config.json(macOS). After editing, restart Claude Desktop.

Note:Claude Desktop does not support auto-detection (MCP roots / CWD-based.imgxrcsearch). UseIMGX_PROJECT_ROOTin the config above (per-client), or runimgx config set project-root /path/to/project(shared across all clients).

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

The samenpxpattern works with Cursor, Windsurf, Continue.dev, Cline, Zed, and other MCP-compatible tools. On Windows, usecmd /c npxinstead ofnpxdirectly.

imgx separatesmodel-independentandmodel-dependentconcerns:

MCP server (tool definitions, stdio transport) CLI (argument parsing, output formatting) ↓ ↓ Core (Capability enum, ImageProvider interface, provider registry, file I/O, history) ↓ Provider (model-specific API calls, capability declarations)

MCP server and CLI are two entry points into the same core. Both call the same provider functions.

Each provider declares its supported capabilities. Adding a new provider means implementing theImageProviderinterface and registering it — no changes to the MCP or CLI layer.

imgx-mcp also works as a standalone command-line tool.

# Generate imgx generate -p "A coffee cup on a wooden table, morning light" -o output.png # Edit imgx edit -i photo.png -p "Change the background to sunset" -o edited.png # Iterative editing imgx edit -i photo.png -p "Make the background darker" imgx edit --last -p "Add warm lighting" imgx edit --last -p "Crop to 16:9" -o final.png # Undo / redo imgx undo # Revert to previous image in session imgx redo # Re-apply an undone edit # History imgx history # Show all sessions and entries imgx history switch <session-id> # Switch to a different session imgx history clear # Clear project history (interactive) imgx history clear --yes # Clear without confirmation imgx history clear --keep-files # Clear history but keep image files imgx history clear --all # Clear ALL history across all projects # Provider management imgx providers # List providers and capabilities imgx capabilities # Detailed capabilities of current provider

imgx config set api-key <key> --provider gemini # Save Gemini API key imgx config set api-key <key> --provider openai # Save OpenAI API key imgx config set model <name> # Set default model imgx config set output-dir <dir> # Set default output directory imgx config set aspect-ratio 16:9 # Set default aspect ratio imgx config set resolution 2K # Set default resolution imgx config list # Show all settings imgx config get api-key # Show a specific setting (API key is masked) imgx config path # Show config file location

imgx init # → creates .imgxrc in current directory

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

Project config is shared via Git. Do not put API keys in.imgxrc.

Detection priority: env var → MCP roots →.imgxrcupward search → user configprojectRoot.

History is saved to<project-root>/.imgx/output-history.json(project-scoped, not shared with other projects). Default image output goes to<project-root>/.imgx/<session-id>/. Relative paths inoutputandoutput_dirare resolved against the project root instead of the MCP server's working directory.
- CLI flags (--model,--output-dir, etc.)
- Environment variables (IMGX_MODEL,IMGX_OUTPUT_DIR, etc.)
- Project config (.imgxrc— searched from current directory upward)
- User config (~/.config/imgx/config.jsonor%APPDATA%\imgx\config.json)
- Provider defaults

{"success": true, "filePaths": ["./output.png"]}

The plugin bundles MCP server + skill in one step. If you prefer not to configure.mcp.jsonand skill files manually:

/plugin marketplace add somacoffeekyoto/imgx-mcp /plugin install imgx-mcp@somacoffeekyoto-imgx-mcp

Update:/plugin→ installed → imgx-mcp → update. If the update shows no changes, uninstall and reinstall.

Uninstall:/plugin uninstall imgx-mcp@somacoffeekyoto-imgx-mcpthen/plugin marketplace remove somacoffeekyoto-imgx-mcp.

git clone https://github.com/somacoffeekyoto/imgx-mcp.git cd imgx-mcp npm install npm run bundle # TypeScript compile + esbuild bundle

- dist/mcp.bundle.js— MCP server entry point
- dist/cli.bundle.js— CLI entry point

Remove theimgxentry from your tool's MCP configuration file.

Delete theimage-generation/directory from.claude/skills/or~/.claude/skills/.

npm uninstallremoves the package but does not delete configuration or generated files. Remove them manually if needed:

# Linux / macOS rm -rf ~/.config/imgx/ # Windows (PowerShell) Remove-Item -Recurse -Force "$env:APPDATA\imgx"

Project history and images:Each project may have a.imgx/directory containing edit history and generated images. Remove it from each project as needed.

- Official page
- GitHub
- npm
- Cursor Directory
- MCP Registry
- SOMA COFFEE KYOTO
- X (@somacoffeekyoto)

Integrates with Google AI Studio/Gemini API for PDF to Markdown conversion and content generation.