imgx

imgx-mcp

AI 画像生成・編集用の MCP サーバーです。Claude Code、Gemini CLI、Cursor、Windsurf、および MCP 互換のあらゆるツールで動作します。

テキストから画像を生成したり、テキストの指示で既存の画像を編集したり、結果を繰り返し調整したりできます。すべて AI コーディング環境から実行できます。

imgx-mcp の特長

• プロンプトエンジニアリング不要 — AI エージェントが会話のコンテキストを維持し、最適化されたプロンプトを自動作成します。必要な内容を伝えるだけで、エージェントがプロンプトの構成、モデルの選択、プラットフォームごとのサイズ調整を行います
• 24 種類の編集テクニックを内蔵 — 雰囲気、構図、スタイル変換、要素の操作、トレンドのスタイルなどを、エージェントが必要に応じて適用するスキルとしてまとめています
• 元に戻す／やり直しに対応したセッション管理 — 繰り返し編集し、任意の時点に戻り、そこから分岐したり、並行するセッションを切り替えたりできます。画像のバージョン管理を実現します

クイックスタート

お使いのツールの MCP 設定（.mcp.json、settings.json など）に追加します。

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

これだけで、AI エージェントが画像を生成・編集できるようになります。

Windows："command": "npx" を "command": "cmd" に置き換え、args 配列の先頭に "/c" を追加してください。

スキル（Claude Code）

Claude Code ユーザー向けに、imgx-mcp には image-generation スキルが含まれています。これは、MCP ツールを効果的に使う方法を Claude に教えるガイド付きプロンプトです。スキルをインストールすると、/image-generation と入力してガイド付きワークフローを開始できます。

スキルのインストール

npm パッケージまたは GitHub リポジトリからスキルディレクトリをコピーして、プロジェクトに配置します。

# 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

スキルファイルは、npm パッケージの skills/ およびGitHub リポジトリに含まれています。

個人用スキル（すべてのプロジェクト）：.claude/skills/ の代わりに ~/.claude/skills/image-generation/ に配置してください。

Claude Desktop

Claude Desktop では ZIP をアップロードしてスキルを利用できます。

1. リポジトリから image-generation-skill.zip をダウンロードします（または、npm パッケージの dist/ から取得します）
2. Claude Desktop で、Settings > Profile > Customize > Skills > Add Skill を選択します
3. ZIP をアップロードします

新しいリリースの後、ZIP を再ダウンロードして再アップロードするとスキルを更新できます。

このスキルでできること

MCP サーバーは、AI に画像を生成・編集する「能力」を提供します。スキルは、それらのツールをうまく使うための「知識」を補います。そのため、プロンプトの構文やモデルの仕様、サービス固有のパラメーターを覚える必要はありません。

• プロンプトを自動で作成 — 「カバー画像が必要です」と伝えるだけで、AI が「被写体・コンテキスト・スタイル」のフレームワークを使って構造化されたプロンプトを作成します。何を表示するか、どこに配置するか、どのように見せるかを指定します。
• 24 種類の編集テクニック — 雰囲気の調整、構図の変更、要素の操作、スタイルの転送など。「暖かみを加えて」や「被写界深度を加えて」と伝えると、AI がモデルに適した指示を選びます。
• インテリジェントなモデル選択 — まずは無料モデルを使用します。ニーズが無料プランの機能を超える場合にのみ、有料プランへのアップグレードを提案し、何が変わるかを説明します。
• プラットフォームに応じたサイズ設定 — 「Twitter OGP」や「App Store のスクリーンショット」と伝えると、AI が適切なアスペクト比と解像度を選びます。ソーシャルメディア、OGP、アプリストア、印刷物、ブログプラットフォームに対応しています。
• トレンドのスタイルテンプレート — ジブリ、箱入りアクションフィギュア、3D クレイ、ピクセルアート、ちびキャラなどに対応しています。スタイルを指定すると、AI が適切なプロンプト構成を適用します。
• 複数画像の一貫性 — デザイントークンとキャラクター DNA テンプレートにより、スライドデッキ、ソーシャルメディアのシリーズ、ブランド素材の視覚的な一貫性を維持します。

画像生成モデルには、すでにこうした機能が備わっています。スキルを使えば、専門知識がなくてもその機能を活用できます。

MCP サーバーとスキルの違い

	MCP サーバー	スキル
機能	AI エージェントに画像ツールを公開します	ツールの使い方を案内するプロンプトです
対応環境	MCP 互換ツール全般	Claude Code、Claude Desktop
インストール	.mcp.json に追加します	スキルファイルをプロジェクトにコピーします
チームでの共有	.mcp.json をリポジトリにコミットします	.claude/skills/ をリポジトリにコミットします

推奨：MCP サーバーをセットアップ（クイックスタート）し、Claude Code を使用する場合はスキルをインストールしてください。

MCP ツール

ツール	説明
generate_image	テキストプロンプトから画像を生成します
edit_image	テキストの指示で既存の画像を編集します
edit_last	最後に生成または編集した画像を編集します（入力パスは不要です）
undo_edit	最後の編集を取り消し、セッション内の前の画像に戻します
redo_edit	取り消した編集をやり直します
edit_history	すべてのセッションと編集履歴をメタデータとともに表示します
switch_session	別の編集セッションに切り替えます
clear_history	プロジェクトの履歴を消去します（画像ファイルの削除も選択できます）
set_output_dir	デフォルトの出力ディレクトリを変更します（既存ファイルの移動も選択できます）
list_providers	利用可能なプロバイダーと機能を一覧表示します

.imgx/ ディレクトリには、編集履歴とデフォルトの画像出力先の両方が保存されます。場所は、プロジェクトルートの検出結果によって異なります。

プロジェクトルート	.imgx/ の場所	履歴
検出された場合	<project-root>/.imgx/	<project-root>/.imgx/output-history.json
検出されない場合	~/Pictures/imgx/（画像のみ）	~/.config/imgx/output-history.json（グローバル）

同じプロジェクトルートを解決するすべてのクライアントで、同じ履歴が共有されます。各セッションには専用のサブディレクトリが作成されます。ファイルパスはレスポンスで返されます。MCP のレスポンスにはインライン画像プレビューが含まれます（base64）。

反復編集

edit_last ツールは、直前の generate_image または edit_image 呼び出しの出力を入力として使用します。これにより、会話形式のワークフローが可能になります。

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

手順の間にファイルパスを指定する必要はありません。

セッション管理

各 generate_image 呼び出しで新しいセッションが開始されます。後続の edit_last 呼び出しは同じセッションに追加され、編集チェーンを形成します。各セッションには独自の出力ディレクトリがあります。

元に戻す／やり直す — 編集チェーンを前後に移動します。

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

元に戻した後に edit_last を呼び出すと、現在の位置から分岐します（破棄されたエントリーとそのファイルはディスクから削除されます）。

ファイル名 — edit_last は、元のファイルに基づいた連番のファイル名を生成します。

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

セッションの切り替え — edit_history を使ってすべてのセッションを確認し、switch_session を使って以前のセッションを再開します。edit_last ツールは、切り替えたセッションの現在の位置を使用します。

出力ディレクトリ — edit_last はセッションの出力ディレクトリを引き継ぎます。generate_image を output_dir を指定して呼び出した場合、そのセッション内で後続するすべての edit_last 呼び出しも同じディレクトリに出力します。output_dir のパスは、セッションメタデータとして output-history.json に記録されます。これは画像ファイルの保存先にのみ影響し、履歴は常に .imgx/（またはグローバル設定ディレクトリ）に保存されます。

API キーの設定

少なくとも 1 つのプロバイダーを設定してください。

Gemini — Google AI Studio からキーを取得します（gemini-2.5-flash-image では無料枠を利用できます）。

imgx config set api-key YOUR_GEMINI_API_KEY --provider gemini

OpenAI — OpenAI Platform からキーを取得します。

imgx config set api-key YOUR_OPENAI_API_KEY --provider openai

キーは ~/.config/imgx/config.json（Linux/macOS）または %APPDATA%\imgx\config.json（Windows）に保存されます。または、MCP 設定の env セクションを使ってキーを渡すか、環境変数を設定してください。

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

使用するプロバイダーの API キーのみを含めてください。少なくとも 1 つ必要です。

ツールごとの MCP 設定

Claude Code

プロジェクトルートの .mcp.json：

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

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 — プロジェクト内に画像を保存するには、プロジェクトのパスを設定します（例："C:\\Users\\you\\my-project"）。空のままにすると、グローバルなデフォルト（~/Pictures/imgx）が使用されます。

設定ファイルの場所：%APPDATA%\Claude\claude_desktop_config.json（Windows）または ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）。編集後、Claude Desktop を再起動してください。

注： Claude Desktop は自動検出（MCP roots / CWD に基づく .imgxrc の検索）をサポートしていません。上記の設定で IMGX_PROJECT_ROOT を指定するか（クライアントごと）、imgx config set project-root /path/to/project を実行してください（すべてのクライアントで共有）。

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

その他のツール

同じ npx パターンは、Cursor、Windsurf、Continue.dev、Cline、Zed など、MCP 互換ツールで使用できます。Windows では、npx を直接実行する代わりに cmd /c npx を使用してください。

プロバイダー

プロバイダー	モデル	機能
Gemini	gemini-2.5-flash-image（Nano Banana — 無料枠、デフォルト）、gemini-3-pro-image-preview（Nano Banana Pro）、gemini-3.1-flash-image-preview（Nano Banana 2）	生成、編集、アスペクト比（最大 14 種類）、解像度（最大 4K）、参照画像、人物制御
OpenAI	gpt-image-1、gpt-image-1.5（より高速、20% 安価）、gpt-image-1-mini（低予算向け）	生成、編集、アスペクト比、複数出力、出力形式（PNG/JPEG/WebP）、背景の透明化

アーキテクチャ

imgx は、モデルに依存しない関心事とモデルに依存する関心事を分離しています。

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 サーバーと CLI は、同じコアへの 2 つのエントリーポイントです。どちらも同じプロバイダー関数を呼び出します。

各プロバイダーは、サポートする機能を宣言します。新しいプロバイダーを追加するには、ImageProvider インターフェースを実装して登録するだけでよく、MCP レイヤーや CLI レイヤーを変更する必要はありません。

機能システム

機能	説明
TEXT_TO_IMAGE	テキストプロンプトから画像を生成します
IMAGE_EDITING	テキストの指示で画像を編集します
ASPECT_RATIO	出力のアスペクト比を制御します
RESOLUTION_CONTROL	出力解像度を制御します
MULTIPLE_OUTPUTS	1 回のリクエストで複数の画像を生成します
REFERENCE_IMAGES	ガイダンスとして参照画像を使用します
PERSON_CONTROL	出力画像で生成する人物を制御します
OUTPUT_FORMAT	出力形式（PNG、JPEG、WebP）を選択します

CLI

imgx-mcp はスタンドアロンのコマンドラインツールとしても動作します。

インストール

npm install -g imgx-mcp

Node.js 18 以降が必要です。

使い方

# 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

CLI オプション

フラグ	短縮形	説明
--prompt	-p	画像の説明、または編集の指示（必須）
--output	-o	出力ファイルのパス（省略時は自動生成）
--input	-i	編集する入力画像（edit コマンドのみ）
--last	-l	直前の出力を入力として使用（edit コマンドのみ）
--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
--resolution	-r	1K、2K、4K
--count	-n	生成する画像の数
--format	-f	出力形式：png、jpeg、webp（OpenAI のみ）
--background	-b	背景：transparent、opaque、auto（OpenAI のみ）
--quality	-q	品質：low、medium、high、auto（OpenAI のみ）
--model	-m	モデル名
--provider		プロバイダー名（デフォルト：gemini）
--output-dir	-d	出力ディレクトリ

設定

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

プロジェクト設定（.imgxrc）

imgx init でテンプレートを生成します：

imgx init
# → creates .imgxrc in current directory

または手動で作成します：

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

プロジェクト設定は Git 経由で共有されます。.imgxrc に API キーを記載しないでください。

プロジェクトルートの設定（3 つの方法）

方法	範囲	設定方法
クライアント設定の IMGX_PROJECT_ROOT 環境変数	クライアントごと（最優先）	claude_desktop_config.json、.mcp.json などの env に追加します
自動検出（MCP roots / .imgxrc の検索）	自動	CLI エージェント（Claude Code、Gemini CLI）で動作します。Claude Desktop では利用できません
imgx config set project-root	マシン上のすべてのクライアント	ユーザー設定（~/.config/imgx/config.json または %APPDATA%\imgx\config.json）に保存されます

検出の優先順位：環境変数 → MCP roots → .imgxrc の上位ディレクトリ検索 → ユーザー設定の projectRoot

履歴は <project-root>/.imgx/output-history.json に保存されます（プロジェクト単位で、他のプロジェクトとは共有されません）。デフォルトの画像出力先は <project-root>/.imgx/<session-id>/ です。output と output_dir の相対パスは、MCP サーバーの作業ディレクトリではなく、プロジェクトルートを基準に解決されます。

設定の解決順序

1. CLI フラグ（--model、--output-dir など）
2. 環境変数（IMGX_MODEL、IMGX_OUTPUT_DIR など）
3. プロジェクト設定（.imgxrc — 現在のディレクトリから上位に向かって検索）
4. ユーザー設定（~/.config/imgx/config.json または %APPDATA%\imgx\config.json）
5. プロバイダーのデフォルト設定

出力形式

すべての CLI コマンドは JSON を出力します：

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

Claude Code プラグイン

このプラグインは MCP サーバーとスキルをまとめてインストールします。.mcp.json とスキルファイルを手動で設定したくない場合は、次の手順を使用します：

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

更新：/plugin → installed → imgx-mcp → update。更新時に変更が表示されない場合は、アンインストールして再インストールしてください。

アンインストール：/plugin uninstall imgx-mcp@somacoffeekyoto-imgx-mcp、続けて /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

ビルドによって 2 つのバンドルが生成されます：

• dist/mcp.bundle.js — MCP サーバーのエントリーポイント
• dist/cli.bundle.js — CLI のエントリーポイント

アンインストール

MCP サーバー

ツールの MCP 設定ファイルから imgx エントリーを削除します。

スキル

.claude/skills/ または ~/.claude/skills/ から image-generation/ ディレクトリを削除します。

CLI

npm uninstall -g imgx-mcp

npm uninstall はパッケージを削除しますが、設定ファイルや生成されたファイルは削除しません。必要に応じて手動で削除してください。

グローバル設定：

# Linux / macOS
rm -rf ~/.config/imgx/

# Windows (PowerShell)
Remove-Item -Recurse -Force "$env:APPDATA\imgx"

**プロジェクトの履歴と画像：**各プロジェクトには、編集履歴と生成された画像を含む .imgx/ ディレクトリがある場合があります。必要に応じて、各プロジェクトから削除してください。

rm -rf <project-root>/.imgx/

ライセンス

MIT — SOMA COFFEE KYOTO

リンク

• 公式ページ
• GitHub
• npm
• Cursor Directory
• MCP Registry
• SOMA COFFEE KYOTO
• X (@somacoffeekyoto)