{
  "markdown": "# imgx-mcp\n\n[![npm version](https://img.shields.io/npm/v/imgx-mcp)](https://www.npmjs.com/package/imgx-mcp)\n[![npm downloads](https://img.shields.io/npm/dw/imgx-mcp)](https://www.npmjs.com/package/imgx-mcp)\n[![Cursor Directory](https://img.shields.io/badge/Cursor_Directory-listed-blue)](https://cursor.directory/plugins/imgx-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow)](https://opensource.org/licenses/MIT)\n\nAI image generation and editing MCP server. Works with Claude Code, Gemini CLI, Cursor, Windsurf, and any MCP-compatible tool.\n\nGenerate images from text, edit existing images with text instructions, iterate on results — all from your AI coding environment.\n\n### What sets imgx-mcp apart\n\n- **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\n- **24 editing techniques built in** — Atmosphere, composition, style transfer, element manipulation, and trending styles — bundled as a Skill your agent applies on demand\n- **Session management with undo/redo** — Edit iteratively, step back to any point, branch off, or switch between parallel sessions — version control for images\n\n## Quick start\n\nAdd to your tool's MCP config (`.mcp.json`, `settings.json`, etc.):\n\n```json\n{\n  \"mcpServers\": {\n    \"imgx\": {\n      \"command\": \"npx\",\n      \"args\": [\"--package=imgx-mcp\", \"-y\", \"imgx-mcp\"],\n      \"env\": { \"GEMINI_API_KEY\": \"your-key\" }\n    }\n  }\n}\n```\n\nThat's it. Your AI agent can now generate and edit images.\n\n> **Windows**: Replace `\"command\": \"npx\"` with `\"command\": \"cmd\"` and prepend `\"/c\"` to the args array.\n\n## Skill (Claude Code)\n\nFor Claude Code users, imgx-mcp includes an `image-generation` skill — a guided prompt that teaches Claude how to use the MCP tools effectively. With the skill installed, type `/image-generation` to start a guided workflow.\n\n### Install the skill\n\nCopy the skill directory from the npm package or GitHub repository to your project:\n\n```bash\n# From npm (after npx has cached the package)\ncp -r $(npm root -g)/imgx-mcp/skills .claude/skills\n\n# Or from the GitHub repository\ncurl -sL https://raw.githubusercontent.com/somacoffeekyoto/imgx-mcp/main/skills/image-generation/SKILL.md \\\n  -o .claude/skills/image-generation/SKILL.md --create-dirs\ncurl -sL https://raw.githubusercontent.com/somacoffeekyoto/imgx-mcp/main/skills/image-generation/references/providers.md \\\n  -o .claude/skills/image-generation/references/providers.md --create-dirs\n```\n\nOr place skill files manually:\n\n```\nyour-project/\n  .mcp.json                              ← MCP server config (Quick start above)\n  .claude/\n    skills/\n      image-generation/\n        SKILL.md                         ← skill prompt\n        references/\n          providers.md                   ← provider reference\n```\n\nThe skill files are included in the [npm package](https://www.npmjs.com/package/imgx-mcp) under `skills/` and in the [GitHub repository](https://github.com/somacoffeekyoto/imgx-mcp/tree/main/skills/image-generation).\n\n> **Personal skill** (all projects): Place in `~/.claude/skills/image-generation/` instead of `.claude/skills/`.\n\n### Claude Desktop\n\nClaude Desktop supports skills via ZIP upload:\n\n1. Download [`image-generation-skill.zip`](dist/image-generation-skill.zip) from the repository (or find it in the [npm package](https://www.npmjs.com/package/imgx-mcp) under `dist/`)\n2. In Claude Desktop: **Settings > Profile > Customize > Skills > Add Skill**\n3. Upload the ZIP\n\n> Update the skill by re-downloading and re-uploading the ZIP after new releases.\n\n### What the Skill brings\n\nThe MCP server gives the AI the *ability* to generate and edit images. The Skill adds the *knowledge* of how to use those tools well — so you don't need to learn prompt syntax, model specifications, or service-specific parameters.\n\n- **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\n- **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\n- **Intelligent model selection** — Starts with the free model. Suggests paid upgrades only when your needs exceed free tier capabilities, and explains what changes\n- **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\n- **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\n- **Multi-image consistency** — Design tokens and character DNA templates maintain visual coherence across slide decks, social media series, and brand assets\n\nThe image generation models already have these capabilities. The Skill is what makes them accessible without specialized knowledge.\n\n### MCP server vs Skill\n\n| | MCP server | Skill |\n|---|---|---|\n| What it does | Exposes image tools to AI agents | Guided prompt for using the tools |\n| Works with | Any MCP-compatible tool | Claude Code, Claude Desktop |\n| Install | Add to `.mcp.json` | Copy skill files to project |\n| Team sharing | Commit `.mcp.json` to repo | Commit `.claude/skills/` to repo |\n\n**Recommended**: Set up the MCP server (Quick start) + install the skill if you use Claude Code.\n\n## MCP tools\n\n| Tool | Description |\n|------|-------------|\n| `generate_image` | Generate an image from a text prompt |\n| `edit_image` | Edit an existing image with text instructions |\n| `edit_last` | Edit the last generated/edited image (no input path needed) |\n| `undo_edit` | Undo the last edit, reverting to the previous image in the session |\n| `redo_edit` | Redo a previously undone edit |\n| `edit_history` | Show all sessions and their edit history with metadata |\n| `switch_session` | Switch to a different editing session |\n| `clear_history` | Clear project history (optionally delete image files) |\n| `set_output_dir` | Change the default output directory (optionally move existing files) |\n| `list_providers` | List available providers and capabilities |\n\nThe `.imgx/` directory holds both edit history and default image output. Its location depends on project root detection:\n\n| Project root | `.imgx/` location | History |\n|---|---|---|\n| Detected | `<project-root>/.imgx/` | `<project-root>/.imgx/output-history.json` |\n| Not detected | `~/Pictures/imgx/` (images only) | `~/.config/imgx/output-history.json` (global) |\n\nAll clients that resolve to the same project root share the same history. Each session gets its own subdirectory. File paths are returned in the response. Inline image preview is included in MCP responses (base64).\n\n### Iterative editing\n\nThe `edit_last` tool uses the output of the previous `generate_image` or `edit_image` call as input. This enables a conversational workflow:\n\n```\n\"Generate a coffee shop interior\" → generate_image\n\"Make the lighting warmer\"        → edit_last\n\"Add a person reading a book\"     → edit_last\n```\n\nNo need to specify file paths between steps.\n\n### Session management\n\nEach `generate_image` call starts a new session. Subsequent `edit_last` calls are added to the same session, forming an edit chain. Each session has its own output directory.\n\n**Undo / Redo** — Step backward and forward through the edit chain:\n\n```\ngenerate → edit_last → edit_last → edit_last\n                                    ↑ current\n                       ← undo_edit\n                       ↑ current\n                            redo_edit →\n                                    ↑ current\n```\n\nAfter undo, calling `edit_last` branches from the current position (abandoned entries and their files are deleted from disk).\n\n**File naming** — `edit_last` generates sequential filenames based on the origin file:\n\n```\ngenerate_image             → cover.png\nedit_last                  → cover-1.png\nedit_last                  → cover-2.png\n\ngenerate_image (no output) → imgx-a1b2c3d4.png\nedit_last                  → imgx-a1b2c3d4-1.png\n```\n\n**Session switching** — Use `edit_history` to see all sessions, then `switch_session` to resume a previous session. The `edit_last` tool will use the current position in the switched session.\n\n**Output directory** — `edit_last` inherits the output directory from the session. If `generate_image` was called with `output_dir`, all subsequent `edit_last` calls in that session output to the same directory. The `output_dir` path is recorded as session metadata in `output-history.json`. This only affects where image files are saved — history always stays in `.imgx/` (or the global config directory).\n\n## API key setup\n\nSet up at least one provider:\n\n**Gemini** — get a key from [Google AI Studio](https://aistudio.google.com/apikey) (free tier available for `gemini-2.5-flash-image`):\n\n```bash\nimgx config set api-key YOUR_GEMINI_API_KEY --provider gemini\n```\n\n**OpenAI** — get a key from [OpenAI Platform](https://platform.openai.com/api-keys):\n\n```bash\nimgx config set api-key YOUR_OPENAI_API_KEY --provider openai\n```\n\nKeys are stored in `~/.config/imgx/config.json` (Linux/macOS) or `%APPDATA%\\imgx\\config.json` (Windows). Alternatively, pass keys via the `env` section in your MCP config, or set environment variables:\n\n```bash\nexport GEMINI_API_KEY=\"your-api-key\"\nexport OPENAI_API_KEY=\"your-api-key\"\n```\n\nOnly include the API keys for providers you want to use. At least one is required.\n\n## MCP configuration by tool\n\n### Claude Code\n\n`.mcp.json` in your project root:\n\n```json\n{\n  \"mcpServers\": {\n    \"imgx\": {\n      \"command\": \"npx\",\n      \"args\": [\"--package=imgx-mcp\", \"-y\", \"imgx-mcp\"],\n      \"env\": { \"GEMINI_API_KEY\": \"your-key\", \"OPENAI_API_KEY\": \"your-key\" }\n    }\n  }\n}\n```\n\n### Gemini CLI\n\n`~/.gemini/settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"imgx\": {\n      \"command\": \"npx\",\n      \"args\": [\"--package=imgx-mcp\", \"-y\", \"imgx-mcp\"],\n      \"env\": { \"GEMINI_API_KEY\": \"your-key\", \"OPENAI_API_KEY\": \"your-key\" }\n    }\n  }\n}\n```\n\n### Claude Desktop\n\n`claude_desktop_config.json`:\n\nmacOS / Linux:\n\n```json\n{\n  \"mcpServers\": {\n    \"imgx\": {\n      \"command\": \"npx\",\n      \"args\": [\"--package=imgx-mcp\", \"-y\", \"imgx-mcp\"],\n      \"env\": {\n        \"GEMINI_API_KEY\": \"your-key\",\n        \"OPENAI_API_KEY\": \"your-key\",\n        \"IMGX_PROJECT_ROOT\": \"\"\n      }\n    }\n  }\n}\n```\n\nWindows:\n\n```json\n{\n  \"mcpServers\": {\n    \"imgx\": {\n      \"command\": \"cmd\",\n      \"args\": [\"/c\", \"npx\", \"--package=imgx-mcp\", \"-y\", \"imgx-mcp\"],\n      \"env\": {\n        \"GEMINI_API_KEY\": \"your-key\",\n        \"OPENAI_API_KEY\": \"your-key\",\n        \"IMGX_PROJECT_ROOT\": \"\"\n      }\n    }\n  }\n}\n```\n\n`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`).\n\nConfig file location: `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows) or `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS). After editing, restart Claude Desktop.\n\n> **Note:** Claude Desktop does not support auto-detection (MCP roots / CWD-based `.imgxrc` search). Use `IMGX_PROJECT_ROOT` in the config above (per-client), or run `imgx config set project-root /path/to/project` (shared across all clients).\n\n### Codex CLI\n\n`.codex/config.toml`:\n\n```toml\n[mcp_servers.imgx]\ncommand = \"npx\"\nargs = [\"--package=imgx-mcp\", \"-y\", \"imgx-mcp\"]\nenv = { GEMINI_API_KEY = \"your-key\", OPENAI_API_KEY = \"your-key\" }\n```\n\n### Other tools\n\nThe 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` directly.\n\n## Providers\n\n| Provider | Models | Capabilities |\n|----------|--------|-------------|\n| Gemini | `gemini-2.5-flash-image` (Nano Banana — **free tier**, default), `gemini-3-pro-image-preview` (Nano Banana Pro), `gemini-3.1-flash-image-preview` (Nano Banana 2) | Generate, edit, aspect ratio (up to 14 ratios), resolution (up to 4K), reference images, person control |\n| OpenAI | `gpt-image-1`, `gpt-image-1.5` (faster, 20% cheaper), `gpt-image-1-mini` (budget) | Generate, edit, aspect ratio, multi-output, output format (PNG/JPEG/WebP), background transparency |\n\n## Architecture\n\nimgx separates **model-independent** and **model-dependent** concerns:\n\n```\nMCP server (tool definitions, stdio transport)    CLI (argument parsing, output formatting)\n ↓                                                 ↓\nCore (Capability enum, ImageProvider interface, provider registry, file I/O, history)\n ↓\nProvider (model-specific API calls, capability declarations)\n```\n\nMCP server and CLI are two entry points into the same core. Both call the same provider functions.\n\nEach provider declares its supported capabilities. Adding a new provider means implementing the `ImageProvider` interface and registering it — no changes to the MCP or CLI layer.\n\n### Capability system\n\n| Capability | Description |\n|------------|-------------|\n| `TEXT_TO_IMAGE` | Generate images from text prompts |\n| `IMAGE_EDITING` | Edit images with text instructions |\n| `ASPECT_RATIO` | Control output aspect ratio |\n| `RESOLUTION_CONTROL` | Control output resolution |\n| `MULTIPLE_OUTPUTS` | Generate multiple images per request |\n| `REFERENCE_IMAGES` | Use reference images for guidance |\n| `PERSON_CONTROL` | Control person generation in output |\n| `OUTPUT_FORMAT` | Choose output format (PNG, JPEG, WebP) |\n\n## CLI\n\nimgx-mcp also works as a standalone command-line tool.\n\n### Install\n\n```bash\nnpm install -g imgx-mcp\n```\n\nRequires Node.js 18+.\n\n### Usage\n\n```bash\n# Generate\nimgx generate -p \"A coffee cup on a wooden table, morning light\" -o output.png\n\n# Edit\nimgx edit -i photo.png -p \"Change the background to sunset\" -o edited.png\n\n# Iterative editing\nimgx edit -i photo.png -p \"Make the background darker\"\nimgx edit --last -p \"Add warm lighting\"\nimgx edit --last -p \"Crop to 16:9\" -o final.png\n\n# Undo / redo\nimgx undo               # Revert to previous image in session\nimgx redo               # Re-apply an undone edit\n\n# History\nimgx history            # Show all sessions and entries\nimgx history switch <session-id>  # Switch to a different session\nimgx history clear      # Clear project history (interactive)\nimgx history clear --yes          # Clear without confirmation\nimgx history clear --keep-files   # Clear history but keep image files\nimgx history clear --all          # Clear ALL history across all projects\n\n# Provider management\nimgx providers          # List providers and capabilities\nimgx capabilities       # Detailed capabilities of current provider\n```\n\n### CLI options\n\n| Flag | Short | Description |\n|------|-------|-------------|\n| `--prompt` | `-p` | Image description or edit instruction (required) |\n| `--output` | `-o` | Output file path (auto-generated if omitted) |\n| `--input` | `-i` | Input image to edit (`edit` command only) |\n| `--last` | `-l` | Use last output as input (`edit` command only) |\n| `--aspect-ratio` | `-a` | `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2` + Gemini 3.x: `1:4`, `1:8`, `4:1`, `4:5`, `5:4`, `8:1`, `21:9` |\n| `--resolution` | `-r` | `1K`, `2K`, `4K` |\n| `--count` | `-n` | Number of images to generate |\n| `--format` | `-f` | Output format: `png`, `jpeg`, `webp` (OpenAI only) |\n| `--background` | `-b` | Background: `transparent`, `opaque`, `auto` (OpenAI only) |\n| `--quality` | `-q` | Quality: `low`, `medium`, `high`, `auto` (OpenAI only) |\n| `--model` | `-m` | Model name |\n| `--provider` | | Provider name (default: `gemini`) |\n| `--output-dir` | `-d` | Output directory |\n\n### Configuration\n\n```bash\nimgx config set api-key <key> --provider gemini   # Save Gemini API key\nimgx config set api-key <key> --provider openai   # Save OpenAI API key\nimgx config set model <name>      # Set default model\nimgx config set output-dir <dir>  # Set default output directory\nimgx config set aspect-ratio 16:9 # Set default aspect ratio\nimgx config set resolution 2K     # Set default resolution\nimgx config list                  # Show all settings\nimgx config get api-key           # Show a specific setting (API key is masked)\nimgx config path                  # Show config file location\n```\n\n### Project config (`.imgxrc`)\n\nGenerate a template with `imgx init`:\n\n```bash\nimgx init\n# → creates .imgxrc in current directory\n```\n\nOr create manually:\n\n```json\n{\n  \"defaults\": {\n    \"model\": \"gemini-2.5-flash-image\",\n    \"outputDir\": \"./assets/images\",\n    \"aspectRatio\": \"16:9\"\n  }\n}\n```\n\nProject config is shared via Git. Do not put API keys in `.imgxrc`.\n\n#### Project root configuration (3 tiers)\n\n| Method | Scope | How to set |\n|--------|-------|------------|\n| `IMGX_PROJECT_ROOT` env var in client config | Per-client (highest priority) | Add to `env` in `claude_desktop_config.json`, `.mcp.json`, etc. |\n| Auto-detection (MCP roots / `.imgxrc` search) | Automatic | Works on CLI agents (Claude Code, Gemini CLI). Not available on Claude Desktop |\n| `imgx config set project-root` | All clients on the machine | Stored in user config (`~/.config/imgx/config.json` or `%APPDATA%\\imgx\\config.json`) |\n\nDetection priority: env var → MCP roots → `.imgxrc` upward search → user config `projectRoot`.\n\nHistory 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 in `output` and `output_dir` are resolved against the project root instead of the MCP server's working directory.\n\n### Settings resolution\n\n1. CLI flags (`--model`, `--output-dir`, etc.)\n2. Environment variables (`IMGX_MODEL`, `IMGX_OUTPUT_DIR`, etc.)\n3. Project config (`.imgxrc` — searched from current directory upward)\n4. User config (`~/.config/imgx/config.json` or `%APPDATA%\\imgx\\config.json`)\n5. Provider defaults\n\n### Output format\n\nAll CLI commands output JSON:\n\n```json\n{\"success\": true, \"filePaths\": [\"./output.png\"]}\n```\n\n## Claude Code plugin\n\nThe plugin bundles MCP server + skill in one step. If you prefer not to configure `.mcp.json` and skill files manually:\n\n```\n/plugin marketplace add somacoffeekyoto/imgx-mcp\n/plugin install imgx-mcp@somacoffeekyoto-imgx-mcp\n```\n\nUpdate: `/plugin` → installed → imgx-mcp → update. If the update shows no changes, uninstall and reinstall.\n\nUninstall: `/plugin uninstall imgx-mcp@somacoffeekyoto-imgx-mcp` then `/plugin marketplace remove somacoffeekyoto-imgx-mcp`.\n\n## Development\n\n```bash\ngit clone https://github.com/somacoffeekyoto/imgx-mcp.git\ncd imgx-mcp\nnpm install\nnpm run bundle    # TypeScript compile + esbuild bundle\n```\n\nThe build produces two bundles:\n\n- `dist/mcp.bundle.js` — MCP server entry point\n- `dist/cli.bundle.js` — CLI entry point\n\n## Uninstall\n\n### MCP server\n\nRemove the `imgx` entry from your tool's MCP configuration file.\n\n### Skill\n\nDelete the `image-generation/` directory from `.claude/skills/` or `~/.claude/skills/`.\n\n### CLI\n\n```bash\nnpm uninstall -g imgx-mcp\n```\n\n`npm uninstall` removes the package but does not delete configuration or generated files. Remove them manually if needed:\n\n**Global configuration:**\n\n```bash\n# Linux / macOS\nrm -rf ~/.config/imgx/\n\n# Windows (PowerShell)\nRemove-Item -Recurse -Force \"$env:APPDATA\\imgx\"\n```\n\n**Project history and images:** Each project may have a `.imgx/` directory containing edit history and generated images. Remove it from each project as needed.\n\n```bash\nrm -rf <project-root>/.imgx/\n```\n\n## License\n\nMIT — [SOMA COFFEE KYOTO](https://github.com/somacoffeekyoto)\n\n## Links\n\n- [Official page](https://somacoffee.net/imgx-mcp/)\n- [GitHub](https://github.com/somacoffeekyoto/imgx-mcp)\n- [npm](https://www.npmjs.com/package/imgx-mcp)\n- [Cursor Directory](https://cursor.directory/plugins/imgx-mcp)\n- [MCP Registry](https://registry.modelcontextprotocol.io)\n- [SOMA COFFEE KYOTO](https://somacoffee.net)\n- [X (@somacoffeekyoto)](https://x.com/somacoffeekyoto)\n",
  "bytes": 20093,
  "sha": "56c6565e53ee47ed16bdff59fda901015fe8b94be959c5d4ff80a86d49001669",
  "repo_slug": "somacoffeekyoto/imgx-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_somacoffeekyoto_imgx_947ecb1a/readme"
}