Gemini Image MCP Server

🚀 Gemini Image MCP Server

Google Gemini AIを使用した画像生成と編集用のモデルコンテキストプロトコル（MCP）サーバーです。結果をガイドするためのオプションのコンテキスト画像をサポートし、専用の編集ワークフローも備えています。デフォルトで正方形（1:1）の形式で、魅力的なソーシャルメディア画像の作成に最適化されています。

✨ 主な機能

• ✨ Google Gemini AIによる画像生成
• 🎨 複数のアスペクト比（1:1、16:9、9:16、4:3、3:4）
• 📱 デフォルトで1:1の形式でソーシャルメディア向けに最適化
• 🎯 カスタムスタイルのサポート
• 🧩 生成をガイドするコンテキスト画像
• ✏️ 余分なオプションを切り替えることなく、既存の素材を修正するための専用の編集ツール
• 🏷️ 透かしのサポート - 生成された結果に透かし画像を重ねる
• 💾 画像をローカルファイルに自動保存
• 📁 柔軟な出力パスの設定
• 🛡️ カスタマイズ可能なセーフティ設定

📦 インストール

1. このリポジトリをクローンします。
2. 依存関係をインストールします。

npm install

3. プロジェクトをビルドします。

npm run build

📚 ドキュメント

環境変数

Google AI APIキーを設定する必要があります。

export GOOGLE_API_KEY="your-api-key-here"

Google AI APIキーの取得方法

1. Google AI Studioにアクセスします。
2. 新しいAPIキーを作成します。
3. キーをコピーし、環境変数として設定します。

クライアント設定

{
  "servers": {
    "gemini-image": {
      "command": "node",
      "args": ["/full/path/to/project/dist/index.js"],
      "env": {
        "GOOGLE_API_KEY": "your-api-key-here"
      }
    }
  }
}

💻 使用例

generate_image

テキストの説明から新しい画像を作成します。必要に応じて、1つ以上の画像を視覚的なコンテキストとして使用できます。新しいコンテンツを生成したい場合にこのツールを使用します。

パラメーター:

• description (文字列、必須): 希望する画像の詳細な説明。
• images (文字列配列、オプション): コンテキストとして使用する画像のパスの配列（絶対パスまたは相対パス）。スタイルやコンテンツを「編集」またはガイドするために使用します。
• aspectRatio (文字列、オプション): 向きのプリセット (square, landscape, portrait)。デフォルト: square。
• style (文字列、オプション): 追加のスタイル（例: "minimalist", "colorful", "professional", "artistic"）。
• outputPath (文字列、オプション): 画像を保存する場所。指定しない場合は、現在のディレクトリに保存されます。
• watermarkPath (文字列、オプション): 重ねる透かし画像のパス。
• watermarkPosition (文字列、オプション): top-left, top-right, bottom-left, bottom-right のいずれか。デフォルト: bottom-right。

使用例:

# 基本的な使用法 - 現在のディレクトリに保存
Generate an image of a mountain landscape at sunset with warm, minimalist style

# コンテキスト画像を使用して構図をガイドする
Generate an image: "Create a futuristic city skyline inspired by this photo", images: ["./reference-skyline.jpg"], aspectRatio: "landscape"

# 複数のコンテキスト画像
Generate an image combining style of a logo and a photo, images: ["./photo.jpg", "./logo.png"], style: "professional"

特定の向き (square, landscape, または portrait) を要求すると、サーバーは自動的に不可視のヘルパー画像 (assets/square.png, assets/landscape.png, または assets/portrait.png) を追加し、Geminiが目標の寸法を尊重するようにします。

edit_image

集中的なテキスト指示を使用して既存の画像を修正します。構造的な変更を明示的に要求しない限り、このツールは元のフレーミングを維持します。

パラメーター:

• description (文字列、必須): 提供された画像に適用する編集を説明する指示。
• image (文字列、必須): 編集したい画像ファイルのパス（絶対パスまたは相対パス）。
• outputPath (文字列、オプション): 編集結果を保存する場所。指定しない場合は、サーバーは作業ディレクトリと自動生成されたファイル名を使用します。

使用例:

# シンプルな編集
Edit image: "Soften skin tones and remove flyaway hairs", image: "./headshot.png"

# 高度なリタッチ
Edit image: "Turn the product label red and add subtle sparkle highlights", image: "./product-shot.jpg"

# カスタムパスと透かし（左上）
Generate an image of a space cat, outputPath: "./images/epic_pizza.png", watermarkPath: "./my_logo.png", watermarkPosition: "top-left"

透かし機能

generate_image ツールは、画像に透かしを追加する機能をサポートしています。

機能:

• 🏷️ 生成されたすべての出力に画像透かしを追加
• 📍 任意のコーナーに配置 (watermarkPosition)
• 📏 スマートなサイズ調整（画像幅の25%、アスペクト比を維持）
• 🎯 一貫した間隔（エッジから3%の余白）
• 🖼️ PNG、JPG、WebPの透かしファイルをサポート
• ⚡ watermarkPath パラメーターが提供された場合のみ適用

使用方法:

# 画像生成時
watermarkPath: "./my-brand-logo.png"

# コンテキスト画像を使用する場合
watermarkPath: "./watermark.jpg"

透かしの仕様:

• 位置: watermarkPosition でコーナーを設定可能
• サイズ: 画像幅の25%（透かしのアスペクト比を維持）
• 余白: 選択したエッジから画像幅の3%
• ブレンドモード: 上に重ねる（透かしが画像の上に表示される）

保存機能:

• デフォルト: 画像はMCPクライアントが実行されたディレクトリに保存されます。
• 自動命名: 説明、日付、時間に基づいて生成されます。
• サポートされる形式: PNG、JPG、WebP（Geminiが返すものに応じて）
• 自動作成: 必要なフォルダが存在しない場合は自動的に作成されます。

🔧 技術詳細

利用可能なスクリプト

• npm run build: TypeScriptをJavaScriptにコンパイルします。
• npm run dev: 自動リロードを伴う開発モードです。
• npm start: コンパイルされたサーバーを実行します。

プロジェクト構造

gemini-image-mcp-server/
├── src/
│   ├── index.ts          # メインサーバーのエントリポイント
│   ├── services/
│   │   └── gemini.ts     # Gemini AIサービス
│   ├── tools/
│   │   ├── index.ts      # ツールのエクスポート
│   │   ├── generateImage.ts  # 新しい画像を作成するツール
│   │   └── editImage.ts      # 既存の画像を編集するツール
│   └── types/
│       └── index.ts      # 型定義
├── dist/                 # コンパイルされたファイル
├── package.json
├── tsconfig.json
└── README.md

トラブルシューティング

エラー: "GOOGLE_API_KEY environment variable is required"

GOOGLE_API_KEY 環境変数にGoogle AI APIキーを設定していることを確認してください。

エラー: "Could not generate image"

• APIキーが有効で、gemini-2.5-flash-image-preview モデルに対する権限があることを確認してください。
• 説明にセーフティフィルターによってブロックされる可能性のある内容が含まれていないことを確認してください。

ファイル保存エラー

• 指定されたパスに書き込み権限があることを確認してください。
• パスが有効でアクセス可能であることを確認してください。
• フォルダを指定する場合は、末尾に / を付けてください。

サーバーが応答しない

• サーバーが正常に実行されていることを確認してください。
• stderrのログを確認してエラーメッセージを確認してください。
• MCPクライアントが正しく設定されていることを確認してください。

📄 ライセンス

MIT

コントリビューション

コントリビューションは歓迎されます。重大な変更を行う前に、issueを開いてください。