Image Generation MCP Server

画像生成 MCP サーバー

これは、互換性のあるクライアント（Cline、Claude Desktop など）から OpenAI の API（gpt-image-1、dall-e-3、dall-e-2）を使って画像を生成できる Model Context Protocol（MCP）サーバーです。

テキストプロンプトやその他のパラメーターを受け取り、画像を生成して、指定したプロジェクトの public ディレクトリに保存する create_image ツールを提供します。

機能

• OpenAI のモデル（gpt-image-1、dall-e-3、dall-e-2）を使って、テキストプロンプトから画像を生成します。
• OpenAI の gpt-image-1 モデルを使い、参照画像を利用して既存の画像を編集・合成します。
• brandSignature パラメーターで、任意のブランドガイドラインを指定できます。
• 画像サイズ、品質、背景の種類（透明または不透明）を指定できます。
• styleDefinitionJSON パラメーターにより、一貫したビジュアルスタイルに対応します。
• LLM クライアントが指定する対象プロジェクトのディレクトリに、生成した画像を保存します。
• LLM の使用方法に関する詳細なドキュメントをソースコード（src/index.ts）内に用意しています。
• 検証用のユニットテストを提供します。

前提条件

1. Node.js： バージョン 18 以降を推奨します。
2. npm： Node.js に付属しています。
3. OpenAI API キー： OpenAI の API キーが必要です。platform.openai.com/api-keys にアクセスして作成してください。gpt-image-1 の利用には、API 組織認証が必要となる場合があります。

インストール

オプション 1：NPX によるインストール（推奨）

画像サーバーをインストールして使用する最も簡単な方法は、NPX を使うことです。この方法では、サーバーを再起動するたびに自動で更新されます。

# You don't need to install or clone anything - just run this command to test
npx -y @dfeirstein/image-server@latest

NPX は npm から最新バージョンをダウンロードして実行します。サーバーを起動するたびに自動で最新の状態に保たれます。

オプション 2：リポジトリのクローン

ソースコードに完全にアクセスしたい場合や、コントリビュートしたい場合は、次の手順に従ってください。

1. リポジトリをクローンする：

   git clone <repository-url> image-mcp-server
   cd image-mcp-server
   

   （GitHub などでホストされた後、<repository-url> を実際の URL に置き換えてください。）

2. 依存関係をインストールする：

   npm ci
   

   このコマンドは、package-lock.json に記載された正確なバージョンをインストールし、依存関係を一貫した状態に保ちます。

3. サーバーをビルドする：

   npm run build
   

   これにより、TypeScript コードがコンパイルされ、dist ディレクトリ内に JavaScript が生成されます。

MCP クライアントの設定

このサーバーを MCP クライアントで使用するには、クライアントの設定ファイルに設定を追加する必要があります。正確なファイルパスはクライアントによって異なります。

• Cline（VS Code 拡張機能）： /Users/<YourUsername>/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json（macOS）
• Claude Desktop： ~/Library/Application Support/Claude/claude_desktop_config.json（macOS） （Windows/Linux ではパスが異なる場合があります。クライアントのドキュメントを確認してください。）
• その他のクライアント（Roo、Cursor、Windsurf など）： MCP 設定ファイルの場所については、各クライアントのドキュメントを確認してください。

クライアントの設定ファイル内にあるメインの "mcpServers": { ... } オブジェクトに、次の設定ブロックを追加してください。プレースホルダーは、実際の絶対パスと API キーに置き換えてください。

NPX によるインストールの場合（推奨）

// Inside "mcpServers": { ... } in your client's settings JSON file:

"image-mcp-server": {
  "command": "npx",
  "args": [
    "-y",                          // Auto-accept installation
    "@dfeirstein/image-server@latest"     // Always fetch the latest version
  ],
  "cwd": "/tmp",                   // Any temporary directory is fine
  "env": {
    // IMPORTANT: Replace with your actual OpenAI API Key
    "OPENAI_API_KEY": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  // --- Standard MCP Settings ---
  "disabled": false,
  "autoApprove": [],      // List tool names to auto-approve (e.g., ["create_image"])
  "transportType": "stdio",
  "timeout": 60
}

// Make sure to add a comma before this block if it's not the first server listed!

この設定では、MCP クライアントを起動するたびにサーバーの最新バージョンが自動でダウンロードされて実行されるため、常に最新の機能とバグ修正を利用できます。

リポジトリを使用したインストールの場合

// Inside "mcpServers": { ... } in your client's settings JSON file:

"image-mcp-server": {
  "command": "node",
  "args": [
    // IMPORTANT: Use the ABSOLUTE path to the built index.js file
    "/path/to/your/cloned/image-mcp-server/dist/index.js"
  ],
  // IMPORTANT: Use the ABSOLUTE path to the server's root directory
  "cwd": "/path/to/your/cloned/image-mcp-server",
  "env": {
    // IMPORTANT: Replace with your actual OpenAI API Key
    "OPENAI_API_KEY": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  },
  // --- Standard MCP Settings ---
  "disabled": false,
  "autoApprove": [],
  "transportType": "stdio",
  "timeout": 60
}

// Make sure to add a comma before this block if it's not the first server listed!

主な設定項目：

• /path/to/your/cloned/image-mcp-server を、このリポジトリをクローンした絶対パスに置き換えてください。
• sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx を、実際のOpenAI API キーに置き換えてください。
• サーバーを有効にするには、disabled が false になっていることを確認してください。

MCP クライアントは、変更を自動で検出してサーバーに接続します。

ツールの使用（create_image）

インストールして設定すると、サーバーから create_image ツールを利用できます。

ドキュメントリソースへのアクセス

サーバーはドキュメントを MCP リソースとして公開しており、LLM はプロンプトを作成する前にアクセスできます。

<access_mcp_resource>
<server_name>image-mcp-server</server_name>
<uri>docs/prompt-recipes</uri>
</access_mcp_resource>


<access_mcp_resource>
<server_name>image-mcp-server</server_name>
<uri>docs/readme</uri>
</access_mcp_resource>

これにより、LLM は画像プロンプトを作成する前にプロンプトレシピのドキュメントを読み、より良い結果を得られます。

• 説明： テキストプロンプトに基づいて新しい画像を生成し、必要に応じてブランディングを適用するか、スタイル定義 JSON を使用して、対象プロジェクトの public フォルダーに保存します。参照画像を指定して既存の画像を編集または組み合わせることもできます。
• 詳細な使用方法とパラメーター： パラメーター（prompt、filename、targetProjectDir、brandSignature、styleDefinitionJSON、model、size、quality、background、referenceImagePaths など）の詳細と、LLM がこのツールを効果的に使用する方法については、このリポジトリの src/index.ts ファイル冒頭にある詳細なドキュメントコメントブロックを参照してください。
• 背景オプション： background パラメーターは、'transparent' または 'opaque'（デフォルト）を指定できます。透明な背景はロゴ、アイコン、オーバーレイに適しており、gpt-image-1 モデルで最適に動作します。透明な背景を使用する場合、形式は PNG または WebP にする必要があります。
• 画像編集： referenceImagePaths（対象プロジェクトの public フォルダーを基準とするパスの配列）を指定すると、ツールは OpenAI の画像編集機能を使用し、プロンプトに基づいてそれらの画像を編集または組み合わせます。画像編集操作では、モデルは自動的に gpt-image-1 に設定されます。
• スタイル定義： 任意の styleDefinitionJSON パラメーターを使用すると、複数の画像にわたって一貫したビジュアルスタイルを定義できます。統一された美的感覚を持つテーマ別の画像コレクションを作成する場合に特に便利です。柔軟で表現力豊かなスタイル定義を可能にするため、JSON 構造はプロンプト内で画像モデルに直接渡されます。
• 出力： 成功すると、{ ok: true, path: "relative/path/to/image.png", operation: "edit"|"generate", ... } を含む JSON オブジェクトを返します。このとき、path はリクエストで指定された targetProjectDir の public フォルダーを基準とする相対パスです。

curl によるテスト例（テストのためにサーバーを手動で起動した後）：

# First, build and start the server from its directory:
# npm run build && node dist/index.js

# In another terminal:
curl -X POST http://localhost:5050/createImage \
  -H 'Content-Type: application/json' \
  -d '{
        "prompt": "A cute otter mascot",
        "filename": "otter-mascot.png",
        "targetProjectDir": "/path/to/your/target/project"
      }'

# Example with background parameter for transparent PNG:
curl -X POST http://localhost:5050/createImage \
  -H 'Content-Type: application/json' \
  -d '{
        "prompt": "A professional logo of a cloud with lightning bolt",
        "filename": "cloud-logo.png",
        "model": "gpt-image-1",
        "background": "transparent",
        "targetProjectDir": "/path/to/your/target/project"
      }'

# Example with image editing and transparent background:
curl -X POST http://localhost:5050/createImage \
  -H 'Content-Type: application/json' \
  -d '{
        "prompt": "Add a glowing blue aura effect around the object",
        "filename": "enhanced-icon.png",
        "model": "gpt-image-1",
        "background": "transparent",
        "referenceImagePaths": ["existing-icon.png"],
        "targetProjectDir": "/path/to/your/target/project"
      }'

# Example with styleDefinitionJSON parameter:
curl -X POST http://localhost:5050/createImage \
  -H 'Content-Type: application/json' \
  -d '{
        "prompt": "Abstract representation of Litigation",
        "filename": "litigation-concept.png",
        "targetProjectDir": "/path/to/your/target/project",
        "styleDefinitionJSON": {
          "output_requirements": {
            "color_mode": "Full Vibrant Color Photography", 
            "style": "Abstract Conceptual Realism",
            "quality": "High-end Professional Photo Shoot"
          },
          "color_palette": {
            "primary_accent": {"name": "Primary Blue", "hex": "#1474F3"},
            "supporting_colors": [
              {"name": "Deep Navy", "hex": "#1C2B4A"},
              {"name": "Warm Neutral", "hex": "#E8D7C1"}
            ],
            "overall_tone": "Predominantly cool with warm accents"
          },
          "strict_exclusions": [
            "No Black and White or Monochrome output",
            "No Text or Writing"
          ]
        }
      }'

(注：サーバーがポート 5050 でリッスンするのは直接実行した場合のみで、MCP stdio 経由で起動した場合はリッスンしません)

開発

サーバーへの貢献や変更を行う場合：

• 開発サーバーの実行： npm run dev（自動で再コンパイルと再起動を行うために tsc -w と nodemon を使用します）
• テストの実行： npm test（vitest を使用します）

Docker のサポート

このリポジトリには、サーバー用のコンテナイメージをビルドするための Dockerfile が含まれています。標準的な MCP クライアント連携では node を使用するため必須ではありませんが、一貫した実行環境の確保や、デプロイのシナリオに役立ちます。

Docker イメージのビルド：

# Navigate to the project directory
cd image-mcp-server
# Build the image
docker build -t image-mcp-server:latest .

(Docker Desktop または Docker Engine がインストールされ、実行中である必要があります)。

コンテナの実行（例 — MCP stdio では使用できません）：

docker run -d --name image-server -e OPENAI_API_KEY="your_api_key" image-mcp-server:latest

(注：このように docker run 経由で実行しても、stdio 通信を想定している MCP クライアントでは直接動作しません。主なインストール方法は、前述のとおりクライアントが node dist/index.js を実行するように設定することです。)

ライセンス

(選択したライセンスをここに追加してください。例：MIT License)