imaginate-mc

OpenAI GPT ImageとGoogle Gemini（Nano Banana）で画像を生成・編集するMCPサーバーです。stdio上で動作し、すべての画像をディスクに保存して、ファイルパスを返します。これにより、アシスタントはその結果を引き続き作業に利用できます。

できること

プロバイダーごとに分けられた6つのツール:

設定したキーに対応するツールだけが登録されます。OPENAI_API_KEY だけを設定し、それ以外の何も設定していない場合、アシスタントには3つのツールだけが表示され、どのツールもGoogle側のキー欠落で失敗したくなることはありません。これが、provider 引数を使う単一ツールにするのではなく、ツールをプロバイダーごとに分けた主な理由です。

Related MCP server: OpenAI Image Generation MCP Server

要件

• Node.js 3 (20以降)

• OpenAI API キー、Gemini API キー、またはその両方

GPT Image モデルを利用するには、OpenAI API の組織認証が必要です。認証を済ませていない場合、OpenAIはリクエストを拒否し、、サーバージがその旨を通知します。

接続

npx で公開済みのパッケージを実行します。リポジトリをクローンしたり、パッケージをグローバルにインストールしたりする必要はありません。

npx -y @pinkpixel/imaginate-mcp

サーバーをクライアントの設定に追加します。Claude Desktop の場合は claude_desktop_config.json を編集し、Claude Code の場合はプロジェクト内の .mcp.json か、ユーザー設定の .mcp.json を使います。

{
  "mcpServers": {
    "imaginate": {
      "command": "npx",
      "args": ["-y", "@pinkpixel/imaginate-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "GEMINI_API_KEY": "...",
        "IMAGINATE_OUTPUT_DIR": "~/Pictures/imaginate"
      }
    }
  }
}

設定を編集したら、クライアントを再起動します。画像ツールが表示されない場合は、imaginate_setup_help を呼び出してみてください。このツールが存在するのはプロバイダーのキーが見つからなかった場合だけです。存在しない?原出?警告 should be: "このツールはプロバイダーのキーが一つも見つからなかった場合にのみ存在し、まだ設定すべきキーの変数を一覧表示します。"

ソースから実行

ローカルでサーバーを開発する場合は、リポジトリをクローンしてビルドします:

git clone https://github.com/pinkpixel-dev/imaginate-mcp.git
cd imaginate-mcp
npm install
npm run build
node dist/index.js

このビルドにMCPクライアントを接続するには、"command": "node" を使い、args に dist/index.js の絶対パスを設定します。

設定

すべての変数は起動時に一度だけ読み込まれ。変更した場合はクライアントを再起動してください。

どのツール呼び出しでも、output_dir で保存先を ファイル名 をオーバーライドできます。

ファイルの仕組み

画像は出力ディレクトリに保存されます。サーバーは決して上書きしません。cat.png という名前のファイルが既に存在する場合、cat-1.png、そして cat-2.png になります。

既定のファイル名は openai-a-red-fox-20260825-134512-071.png のような形式になります。これは、プロバイダーのプレフィックス、プロンプトの言葉、タイムスタンプを結合したものです。特定の名前を付けたい場合は filename を渡してください。

編集の元画像はローカルファイルである必要があります。絶対パスを渡してください。このツールはリモートのURLをダウンロードしないため、Web上にあるファイルは先に取得しておいてください。元のソースファイルは読み取り専用で、変更されることはありません。

使用方法

サーバーを接続したら、後は基本的には通常通りアシスタントと会話するだけです。ただ、知っておくと便利なポイントがいくつがあります。

プロバイダーの選択

両方のプロバイターは、それぞれ異なる分野に優れています。

Gemini は、画像内の文字、世界の知識、インフォグラフィックの制作に強く、描く前に Google 検索のグラウンディングもできます。また、インタラクションIDを返すため、画像を再度アップロードすることなく、調整を続けられます。

GPTにも対応しています。 GPT Image は、詳細なレイアウトの指示書にもまた忠実です。サイズ、品質、背景を細々と調整できます。透明背景が必要な場合ってはこれを使えば良いのですが、gpt-image-2 は透明対応が廃止されたため、gpt-image-1.5 以前のモデルが必要です。

Gemini 画像の反復調整

Gemini のすべての結果にインタラクションID が含まれます。次の gemini_edit_image 呼び出しで、previous_interaction_id としてそのまま渡して、画像の再送信を省略できます:

1. 自分のプロンプトを使って処理 generate_image すると、結果にインタラクションID を取得します。

2. previous_interaction_id を渡して「横書きにして」というプロンプトで gemini_edit_image を呼び出します。

再アップロードするよりも低コスト scraping で、複数ラウンドの間も画像の一貫性が保たれもします。

編集と合成

両方の *_edit_image ツールは、いずれの同じインターフェースで複数のタスクを扱います。画像パスを1つ渡せばその画像を編集し、複数渡せばそれらを組み合わせて新しいシーンを構成します。

マスクしたインペイントインティングでは、2つのプロバイダーの方法が異なります。OpenAI は実際にアルファチャンネルを持つマスク PNG を渡し、mask として指定する必要があります。Gemini はセマンティックな処理を行うため、「空のみを変更して、他はすべてそのまま」という風に指示するだけで、マスクファイルは不要です。

参照画像の上限は Gemini のモデルにより異なります: Lite で 14 オー、Nano Banana では 10 枚、Pro では 6 枚が。gemini_list_models で確認してください。

開発

npm run build      # compile to dist/
npm run watch      # compile on change
npm run typecheck  # types only, no output
npm test           # compile tests and run them

テストにはNode.js組み込みのテストランナーを使用します。ファイルの命名と保存ロジック、Geminiのレスポンス解析、エラーメージのマッピングをカバーしています。どちらのAPIも呼び出さないため、キーがなくても実行できます。

構成する。

src/
  index.ts               entry point, conditional tool registration
  config.ts              environment parsing
  lib/                   file handling, errors, result formatting, model catalog
  providers/openai/      OpenAI client wrapper and tool definitions
  providers/google/      Gemini client wrapper and tool definitions
tests/

制限事項

• 画像元はローカルファイルである必要があります。リモートURLには使用できません。

• ストリーミングと部分的な画像には対応していません。呼び出しは画像が完成されたとき戻ります。

• Gemini では要求した image 数を確実に守られないため、呼び出しごとに画像 one one を生成を依頼してしてください。OpenAI ツールでは n を許可して、標準で機能します。

• OpenAI は、複雑なプロンプトで最大2分かかることがあります。これはAPI側の遅延であり、標準的です。

• Gemini の画像すべてには、目に見えない SynthID のウォーターマークががまれれます。

• モデルIDと料金は両方すばやく変わります。一覧ツールがはこのバージョンの既知の情報を表示します。それは、あなたのアカウントで実際に届ける範囲と乖離があるます。

ライセンス

Apache 2.0.詳しくは LICENSE を参照してください。

Pink Pixel からたい愛を込めて。