image-generation-mcp

エージェントに画像を頼むと、base64 の壁ではなくファイルパスが返ってきます。 サーバーは Gemini または OpenAI で画像を生成し、ディスクに書き出して、 絶対パスのみを返します。コンテキスト・ウィンドウはクリーンなままで、ファイるは エージェントが開いたり、移動したり、別のツールに渡したりできる場所にあります。

機能

• ツール1つ、手間いらず。 generate_image(prompt, images, aspect_ratio) — これが API のすべてです。

• ペイロードではなくパス。 絶対ファイルパスを返すので、1.5 MB の PNG は ~200万トークンの代わりに ~60トークンで済みます。

• 2つのプロバイダー、自動選択。 持っている方の API キーを設定するだけ。両方設定している場合? IMAGE_PROVIDER が決めます。

• 画像から画像へ。 最大4枚の参照画像を渡して、リスタイル、編集、合成ができます。

• 柔軟な入力。 参照画像はローカルパス、http(s):// URL、data: URI、または素の base64 のいずれでもよく、サーバーが自動判別します。

• 両方のトランスポート。 ローカルクライアントには stdio、ポートが必要なときはストリーミング可能な HTTP (localhost バインド)。

• 正直なエラー。 不正なキーを隠すリトライも、プロバイダーを黙って切り替えることもありません。API が 429 を返せば、429 が見えます。

• 読めるサイズ。 ソース約 ~540行、100行超のファイるなし、全体が strict 型付き。

Related MCP server: VisionToolMCP

前提条件

課金についての注意。 画像モデルはどちらのプロバイダーでも無料枠ではありません。課金が有効になっていない GeminI キーは、すべての画像モデルで 429 ... limit: 0 を返します。

クイックスタート

git clone https://github.com/farukcan/image-generation-mcp.git
cd image-generation-mcp
uv sync

cp .env.example .env      # add OPENAI_API_KEY or GEMINI_API_KEY
uv run pytest -m smoke    # generates a real image into out/

その最後のコマンドは、キーがエンドツーエンドで動作することを確認する最も速い方法です — 生成した画像のパスを表示します。

エージェントに追加する

Claude Code

claude mcp add image-generation \
  -e OPENAI_API_KEY=sk-... \
  -- uvx --from git+https://github.com/farukcan/image-generation-mcp image-generation-mcp

uvx は初回実効時にパッケージを取得・ビルド・キッシュします — 事前にインストールするものも、手で更新するものもありません。

編集できるチェックアウトが好みですか? その場合はディレクトリを指定してください:

claude mcp add image-generation \
  -e OPENAI_API_KEY=sk-... \
  -- uv run --directory /absolute/path/to/image-generation-mcp image-generation-mcp

-s user を追加すると、このプロジェクトだけでなく、すべてのプロジェクトで利用できます。claude mcp list で確認し、claude mcp remove image-generation で削除します。

Gemini CLI

同じフラグ、同じ構成:

gemini mcp add image-generation \
  -e OPENAI_API_KEY=sk-... \
  -- uvx --from git+https://github.com/farukcan/image-generation-mcp image-generation-mcp

Cursor、Windsurf、Claude Desktop、その他

これらは JSON 設定ファイル (.cursor/mcp.json、claude_desktop_config.json、…) を読み取ります。エントリはどこでも同じです:

{
  "mcpServers": {
    "image-generation": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/farukcan/image-generation-mcp",
        "image-generation-mcp"
      ],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "OUT_DIR": "/absolute/path/where/images/should/land"
      }
    }
  }
}

GUI クライアントでは OUT_DIR を明示的に設定してください — 想定外の作業ディレクトリで起動されることがよくあり、out/ はそこに作られてしまいます。

HTTP サービスとして

uv run image-generation-mcp --transport http --port 8000

ストリーミング可能な HTTP エンドポイントを http://127.0.0.1:8000/mcp で提供します。ループバックのみにバインドし、認証がないため、公開する前にはプロキシの背後に置いてください。

ツール

generate_image(prompt: str, images: list[str] | None = None, aspect_ratio: str = "1:1") -> str

書き出されたファイルの絶対パスを返します (例: /path/to/out/20260827-172746-c9b3.png)。名前は YYYYmmdd-HHMMSS-xxxx なので、結果は時系列に並び、衝突することもありません。

アスペクト比について: Gemini は10種類すべてに対応します。OpenAI は3サイズのみ受け付けるため、比率は最も近い 1024x1024、1536x1024、1024x1536 のいずれかに丸められます — そこで 16:9 を要求しても 3:2 になります。

設定

すべての設定は環境変数です。作業ディレクトリ (または上位のディレクトリ) にある .env ファイルがフォールバックとして読み込まれますが、実際の環境変数が常に優先されます。

API キーを一切設定せずにサーバーを起動すると、最初のリクエストは明確に失敗し、探していた変数を列挙します。

動作の仕組み

flowchart LR
    A([MCP client]) -->|generate_image| B[server.py]
    B --> C[aspect.py<br/>validate ratio]
    B --> D[sources.py + download.py<br/>path / URL / base64 → bytes]
    B --> E{"registry.py<br/>which provider?"}
    E -->|GEMINI_API_KEY| F[gemini_provider.py<br/>Interactions API]
    E -->|OPENAI_API_KEY| G[openai_provider.py<br/>generate / edit]
    F --> H[output.py<br/>write into OUT_DIR]
    G --> H
    H -->|absolute path| A

各モジュールは1つのことだけを行い、100行未満に収めています。プロバイダーは解決済み設定ごとにキャッシュされるため、SDK クライアントとそのコネクションプールは、リクエストごとに再構築されるのではなく、呼び出し間で再利用されます。

プロバイダー

知っておく価値のある意図的な癖が2つあります:

• Gemini の画像 response_format は、明示的な MIME タイプとして image/jpeg のみを受け付けるため、サーバーはそれを要求せず、返ってきたものに合わせてファイル名を付けます。

• input_fidelity は OpenAI には送信されません — gpt-image-2 はそれを 400 で拒否し、自ら高フィデリティを適用するためです。

開発

uv run ruff check . && uv run ruff format --check .
uv run mypy
uv run pytest              # unit tests, all providers mocked
uv run pytest -m smoke -s  # real API calls; costs money, prints the paths

スモークテストはデフォルトで選択対象から除外されているため、通常の pytest 実行でお金がかかることはありません。test_edits_a_real_image は自分用の参照画像を生成するため、2回分の生成コストがかかります。

ロゴもスクリーンショットも生成されています — SVG ではなくスクリプトを編集してください:

uv run python media/generate_logo.py
uv run python media/generate_screenshot.py

1ファイル100行という上限は、偶然ではなく設計上の制約です: すべてのモジュールを1画面でレビュー可能に保ちます。拡張するのではなく分割してください。

トラブルシューティング

ライセンス

MIT © Ömer Faruk Can