imgx-mcp 使い方ガイド

AI コーディング環境から画像を生成・編集できる MCP サーバー。Claude Code、Gemini CLI、Claude Desktop、Cursor、Windsurf など MCP 対応ツールで動作する。テキストで指示を出すだけで画像を作成でき、結果を見ながら繰り返し修正できる。

1. クイックスタート

Step 1: MCP 設定

プロジェクトルートの .mcp.json に以下を追加する。

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

Windows の場合: "command" を "cmd" に、"args" の先頭に "/c" を追加する。

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

Step 2: API キー取得

いずれか1つのプロバイダの API キーが必要。

プロバイダ	取得先	備考
Gemini（デフォルト）	Google AI Studio	無料枠あり
OpenAI	OpenAI Platform	有料

取得したキーを .mcp.json の env セクションに設定する。または CLI で設定することもできる。

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

キーは ~/.config/imgx/config.json（Linux/macOS）または %APPDATA%\imgx\config.json（Windows）に保存される。

Step 3: 最初の画像生成

設定が完了したら、AI に「画像を生成して」と伝えるだけで動作する。

「コーヒーカップの画像を生成して」

AI が generate_image ツールを呼び出し、画像を生成する。ファイルパスが返され、対応クライアントではインライン表示もされる。

生成された画像は ~/Pictures/imgx/ に保存される（デフォルト）。

2. MCP ツール一覧

imgx-mcp は 4 つの MCP ツールを提供する。Bash コマンドは不要で、AI エージェントが直接呼び出す。

generate_image

テキストプロンプトから画像を生成する。

パラメータ	必須	説明
`prompt`	はい	画像の説明
`aspect_ratio`	いいえ	`1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2`
`resolution`	いいえ	`1K`, `2K`, `4K`
`count`	いいえ	生成枚数（OpenAI のみ、最大 4）
`model`	いいえ	モデル名
`provider`	いいえ	`gemini`（デフォルト）または `openai`
`output`	いいえ	出力ファイルパス
`output_dir`	いいえ	出力ディレクトリ

edit_image

既存の画像をテキスト指示で編集する。マスク不要。モデルがテキストから変更箇所を判断する。

パラメータ	必須	説明
`input`	はい	編集する画像のパス
`prompt`	はい	編集の指示
`aspect_ratio`	いいえ	出力アスペクト比
`resolution`	いいえ	出力解像度
`output`	いいえ	出力ファイルパス

edit_last

直前に生成または編集した画像を編集する。入力パスの指定は不要で、前回の出力が自動的に使われる。

パラメータ	必須	説明
`prompt`	はい	編集の指示
`aspect_ratio`	いいえ	出力アスペクト比
`resolution`	いいえ	出力解像度
`output`	いいえ	出力ファイルパス

list_providers

利用可能なプロバイダとその機能を一覧表示する。パラメータなし。

3. 実用ワークフロー

ブログカバー画像

生成してからレビューし、必要に応じて edit_last で調整する。

1. generate_image: prompt="ラップトップとターミナルが映る開発者のデスク、コーヒーカップ、朝の光"
                   aspect_ratio="16:9" resolution="2K"
2. 結果を確認
3. edit_last: prompt="色味をもっと暖かく"（変更が必要な場合）
4. edit_last: prompt="ビネット効果を加える"（さらに調整）

反復編集

edit_last を連鎖させることで、会話的に画像を修正していく。ファイルパスの指定は不要。

generate_image → edit_last → edit_last → edit_last → 完成

AI に「もう少し明るくして」「背景を変えて」と伝えるだけで、前回の結果をベースに修正が行われる。

プロバイダ比較

同じプロンプトを異なるプロバイダで生成し、結果を比較できる。

1. generate_image: prompt="..." provider="gemini"
2. generate_image: prompt="..." provider="openai"
3. 両方の結果を比較して選択
4. 選んだ方を edit_last で調整

アイコンバリエーション

OpenAI の count パラメータで複数枚を一度に生成するか、Gemini ではプロンプトを少しずつ変えて複数回生成する。

# OpenAI: 一度に複数生成
generate_image: prompt="ミニマルなコーヒー豆アイコン、白背景"
                aspect_ratio="1:1" count=3 provider="openai"

# Gemini: プロンプトを変えて繰り返す
generate_image: prompt="ミニマルなコーヒー豆アイコン、白背景、線画"
generate_image: prompt="ミニマルなコーヒー豆アイコン、白背景、フラットデザイン"

4. 各環境の設定

各ツールの MCP 設定ファイルに imgx-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" }
    }
  }
}

使用するプロバイダのキーだけ設定すればよい。

Claude Code では Plugin としてもインストールできる。 /plugin install imgx-mcp で MCP サーバーの登録と Skill（使い方ガイド）が一度にインストールされる。.mcp.json を手動編集せずに使いたい場合に便利。

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

設定ファイルの場所:

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

編集後、Claude Desktop を再起動する。

補足: Claude Desktop は MCP サーバーをアプリ自身のディレクトリから実行する。画像の出力先を指定したい場合は env セクションに "IMGX_OUTPUT_DIR": "C:\\Users\\you\\Pictures" を追加するか、事前に imgx config set output-dir <path> を実行する。

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

その他のツール（Cursor、Windsurf 等）

同じ npx パターンが Cursor、Windsurf、Continue.dev、Cline、Zed など MCP 対応ツールで使える。Windows では npx の代わりに cmd /c npx を使用する。

5. 設定の管理

imgx-mcp の設定は 5 つのレイヤーで解決される。上位が優先される。

優先度	レイヤー	例
1（最高）	ツールパラメータ / CLI フラグ	`--model`, `--output-dir`
2	環境変数	`IMGX_MODEL`, `IMGX_OUTPUT_DIR`
3	プロジェクト設定	`.imgxrc`（カレントディレクトリ）
4	ユーザー設定	`~/.config/imgx/config.json`
5（最低）	プロバイダデフォルト	各プロバイダの初期値

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

プロジェクトルートに .imgxrc を配置することで、プロジェクト固有のデフォルト値を設定できる。

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

.imgxrc は Git で共有できる。API キーは .imgxrc に含めず、ユーザー設定または環境変数で管理する。

ユーザー設定

imgx config コマンドで設定を管理できる。

imgx config set model gemini-2.5-flash-image    # デフォルトモデルの変更
imgx config set output-dir ./images              # 出力先の変更
imgx config set aspect-ratio 16:9                # アスペクト比の変更
imgx config list                                 # 全設定の表示
imgx config path                                 # 設定ファイルの場所

MCP サーバーでの環境変数

.mcp.json の env セクションで環境変数を渡せる。

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

6. プロバイダ比較

Gemini vs OpenAI

機能	Gemini	OpenAI
テキストから画像生成	対応	対応
テキスト指示による編集（マスク不要）	対応	対応
反復編集（`edit_last`）	対応	対応
解像度指定（1K / 2K / 4K）	対応	非対応
複数枚同時生成	非対応	対応（最大 4 枚）
出力フォーマット選択	PNG のみ	PNG / JPEG / WebP
無料枠	あり	なし

Gemini モデル比較

項目	gemini-3-pro-image-preview	gemini-2.5-flash-image
画質	高い	良好
速度	遅め	速い
コスト	約 $0.134/枚	低い
解像度	1K, 2K, 4K	1K, 2K

使い分け

Gemini: デフォルトプロバイダ。無料枠がある。解像度指定が必要な場合に適している
OpenAI: 複数枚の同時生成、フォーマット選択が必要な場合に使用する
gemini-3-pro: 高画質が必要なとき（カバー画像、OGP 等）
gemini-2.5-flash: 速度とコストを優先するとき（ラフ案、繰り返しの試行）

7. CLI（補足）

imgx-mcp は MCP サーバーとしての利用が主な用途だが、コマンドラインツールとしても使える。

インストール

npm install -g imgx-mcp

Node.js 18 以上が必要。

基本コマンド

# 画像生成
imgx generate -p "木製テーブルの上のコーヒーカップ、朝の光" -o output.png

# 画像編集
imgx edit -i photo.png -p "背景を夕焼けに変更" -o edited.png

# 反復編集（--last で前回の出力を入力として使用）
imgx edit -i photo.png -p "背景を暗くする"
imgx edit --last -p "暖かい照明を追加"
imgx edit --last -p "16:9 にクロップ" -o final.png

# プロバイダ確認
imgx providers

主なフラグ

フラグ	短縮	説明
`--prompt`	`-p`	画像の説明または編集の指示（必須）
`--output`	`-o`	出力ファイルパス（省略時は自動生成）
`--input`	`-i`	編集する入力画像（`edit` コマンドのみ）
`--last`	`-l`	前回の出力を入力として使用（`edit` コマンドのみ）
`--aspect-ratio`	`-a`	アスペクト比
`--resolution`	`-r`	解像度
`--count`	`-n`	生成枚数
`--provider`		プロバイダ名（デフォルト: `gemini`）
`--model`	`-m`	モデル名

詳細は README を参照。

imgX-MCP – 導入方法・使い方

imgx-mcp 使い方ガイド

1. クイックスタート

Step 1: MCP 設定

Step 2: API キー取得

Step 3: 最初の画像生成

2. MCP ツール一覧

generate_image

edit_image

edit_last

list_providers

3. 実用ワークフロー

ブログカバー画像

反復編集

プロバイダ比較

アイコンバリエーション

4. 各環境の設定

Claude Code

Gemini CLI

Claude Desktop

Codex CLI

その他のツール（Cursor、Windsurf 等）

5. 設定の管理

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

ユーザー設定

MCP サーバーでの環境変数

6. プロバイダ比較

Gemini vs OpenAI

Gemini モデル比較

使い分け

7. CLI（補足）

インストール

基本コマンド

主なフラグ

リンク

imgx-mcp 使い方ガイド

1. クイックスタート

Step 1: MCP 設定

Step 2: API キー取得

Step 3: 最初の画像生成

2. MCP ツール一覧

generate_image

edit_image

edit_last

list_providers

3. 実用ワークフロー

ブログカバー画像

反復編集

プロバイダ比較

アイコンバリエーション

4. 各環境の設定

Claude Code

Gemini CLI

Claude Desktop

Codex CLI

その他のツール（Cursor、Windsurf 等）

5. 設定の管理

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

ユーザー設定

MCP サーバーでの環境変数

6. プロバイダ比較

Gemini vs OpenAI

Gemini モデル比較

使い分け

7. CLI（補足）

インストール

基本コマンド

主なフラグ

リンク

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