openai-gpt-image-mcp

openai-gpt-image-mcp

---

OpenAI の GPT-4o/gpt-image-1 画像生成・編集 API 向けの Model Context Protocol（MCP）ツールサーバーです。

• OpenAI の最新モデルを使い、テキストプロンプトから画像を生成します。
• 高度なプロンプト制御で画像を編集（インペインティング、アウトペインティング、合成）します。
• 対応クライアント：Claude Desktop、Cursor、VSCode、Windsurf、および MCP 対応のすべてのクライアント。

---

✨ 機能

• create-image：高度なオプション（サイズ、品質、背景など）を指定して、プロンプトから画像を生成します。
• edit-image：プロンプトとオプションのマスクを使って画像を編集または拡張します。ファイルパスと base64 入力の両方に対応しています。
• ファイル出力：生成した画像をディスクに直接保存するか、base64 形式で受け取れます。

---

🚀 インストール

git clone https://github.com/SureScaleAI/openai-gpt-image-mcp.git
cd openai-gpt-image-mcp
yarn install
yarn build

---

🔑 設定

Claude Desktop または VSCode（Cursor/Windsurf を含む）の設定に追加します。

{
  "mcpServers": {
    "openai-gpt-image-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": { "OPENAI_API_KEY": "sk-..." }
    }
  }
}

Azure のデプロイにも対応しています。

{
  "mcpServers": {
    "openai-gpt-image-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": { 
        "AZURE_OPENAI_API_KEY": "sk-...",
        "AZURE_OPENAI_ENDPOINT": "my.endpoint.com",
        "OPENAI_API_VERSION": "2024-12-01-preview"
      }
    }
  }
}

環境ファイルの指定にも対応しています。

{
  "mcpServers": {
    "openai-gpt-image-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js", "--env-file", "./deployment/.env"]
    }
  }
}

---

⚡ 高度な設定

• create-image では、n を設定すると一度に最大 10 枚の画像を生成できます。
• edit-image では、編集する領域を指定するためにマスク画像（ファイルパスまたは base64）を指定します。
• --env-file path/to/file/.env で環境ファイルを指定します。
• すべてのオプションについては src/index.ts を参照してください。

---

🧑‍💻 開発

• TypeScript ソース：src/index.ts
• ビルド：yarn build
• 実行：node dist/index.js

---

📝 ライセンス

MIT

---

🩺 トラブルシューティング

• OPENAI_API_KEY が有効で、画像 API を利用できることを確認してください。
• 認証済みの OpenAI 組織が必要です。認証後、画像 API が有効になるまで 15～20 分かかる場合があります。
• ファイルパスは絶対パスで指定してください。
  • Unix/macOS/Linux：/ で始まるパス（例：/path/to/image.png）
  • Windows：ドライブ文字の後に : を付けたパス（例：C:/path/to/image.png または C:\path\to\image.png）
• ファイルを出力する場合は、ディレクトリへの書き込みが可能であることを確認してください。
• ファイル形式に関するエラーが表示された場合は、画像ファイルの拡張子と形式を確認してください。

---

⚠️ 制限と大きなファイルの処理

• ペイロードの上限は1MBです： MCP クライアント（Claude Desktop を含む）には、ツールの応答に1MBの厳格な上限があります。大きな画像（特に高解像度の画像や複数の画像）は、base64 で返すと簡単にこの上限を超えることがあります。
• ファイル出力への自動切り替え： 画像の合計サイズが1MBを超えると、ツールは画像を自動的にディスクに保存し、base64 の代わりにファイルパスを返します。これにより互換性が確保され、result exceeds maximum length of 1048576 のようなエラーを防げます。
• デフォルトの保存先： file_output のパスを指定しない場合、画像は一意のファイル名で /tmp（または MCP_HF_WORK_DIR 環境変数で設定されたディレクトリ）に保存されます。
• 環境変数：
  • MCP_HF_WORK_DIR：大きな画像やファイル出力の保存先を設定します。例：export MCP_HF_WORK_DIR=/your/desired/dir
• ベストプラクティス： 大きな画像や本番環境用の画像には、必ずファイル出力を使用し、クライアントがファイルパスを処理できるよう設定してください。

---

📚 参考資料

• OpenAI Images API ドキュメント

---

🙏 クレジット

• @modelcontextprotocol/sdk を使用して構築
• openai Node.js SDK を使用
• SureScale.ai によって構築
• Axle Research and Technology からの貢献