Gemini 2.5 Flash Image MCP

🚀 Gemini 2.5 Flash Image MCP

GoogleのGemini 2.5 Flash Image Previewを使用した会話型画像生成と編集用のモデルコンテキストプロトコル（MCP）サーバーです。Claude Codeや他のMCPクライアントから簡単にインストールして使用できるように設計されています。

✨ 主な機能

• テキストから画像の生成：詳細なプロンプトから画像を生成します。
• 画像編集：自然言語の指示で画像を編集します。
• 複数画像の合成 / スタイル転送：画像を合成したり、スタイルを転送します。
• ファイル保存オプション：Base64形式の画像を返し、必要に応じてファイルに保存します。
• プロバイダー非依存のMCP：MCP対応のクライアントであればどこでも動作します。

📦 インストール

必要条件

• Node.js 18 以上
• MCPクライアント（Claude Code、Cursor、VS Code、Windsurfなど）
• Google Gemini APIキー：GEMINI_API_KEY を設定する必要があります。

Gemini APIキーの取得

Google AI StudioからAPIキーを取得するには、以下の手順に従ってください。

1. Google AI Studioを開き、サインインします：https://aistudio.google.com/apikey
2. 「APIキーを作成」をクリックします（既にキーがある場合は「キーを管理」）
3. 生成されたキーをコピーします
4. このサーバーを実行する際に、マシンの環境変数として設定します。

例:

# macOS / Linux (bash/zsh)
export GEMINI_API_KEY="YOUR_API_KEY"

# Windows PowerShell
$env:GEMINI_API_KEY="YOUR_API_KEY"

クイックスタート

まず、クライアントでMCPサーバーをインストールします。以下の例はClaude Codeの使用を中心に説明しています。

標準設定 はほとんどのツールで動作します。

{
  "mcpServers": {
    "gemini-2-5-flash-mcp": {
      "command": "npx",
      "args": ["@taiyokimura/gemini-2-5-flash-mcp@latest"]
    }
  }
}

クイック使用法 (Claude Code)

# npx（非対話フラグ付き） + APIキー同時指定（Claudeの -e 指定）
claude mcp add gemini-2-5-flash-mcp -s user -e GEMINI_API_KEY="YOUR_API_KEY" -- npx -y @taiyokimura/gemini-2-5-flash-mcp@latest

# グローバルインストール + APIキー同時指定（Claudeの -e 指定）
npm i -g @taiyokimura/gemini-2-5-flash-mcp \
  && claude mcp add gemini-2-5-flash-mcp -s user -e GEMINI_API_KEY="YOUR_API_KEY" -- gemini-2-5-flash-mcp

# HTTP モードで登録（SSE既定）例（対応クライアントのみ）
# ※ HTTP モードはこのプロセス自体がHTTPサーバとして常駐します
claude mcp add gemini-2-5-flash-mcp -s user \
  -e GEMINI_API_KEY="YOUR_API_KEY" \
  -e MCP_TRANSPORT="http" \
  -e MCP_HTTP_PORT="7801" \
  -e MCP_HTTP_PATH="/mcp" \
  -- npx -y @taiyokimura/gemini-2-5-flash-mcp@latest

ストリーマブルHTTPモード（実験的）

STDIOの代わりにストリーマブルHTTPを使用することもできます。MCPクライアントがストリーマブルHTTPに対応している場合のみ利用してください。

1. サーバーをHTTPモードで起動

export MCP_TRANSPORT=http
export GEMINI_API_KEY=YOUR_API_KEY
# 任意（既定: 7801, /mcp, SSE）
export MCP_HTTP_PORT=7801
export MCP_HTTP_PATH=/mcp
export MCP_HTTP_ENABLE_JSON=false

npm run build
node ./build/index.js
# => HTTP transport listening on http://localhost:7801/mcp

2. クライアント側設定（例: ストリーマブルHTTP対応クライアント）

• タイプ: HTTP (Streamable)
• URL: http://localhost:7801/mcp

注:

• SSEストリーミングが既定です。JSONレスポンスで使いたい場合は MCP_HTTP_ENABLE_JSON=true を設定します。
• セッションはサーバー側で生成されます（stateful）。完全にstatelessにしたい場合はコード側で sessionIdGenerator: undefined に変更することができます。

claude mcp add gemini-2-5-flash-mcp -s user -- npx @taiyokimura/gemini-2-5-flash-mcp@latest

claude mcp remove gemini-2-5-flash-mcp

code --add-mcp '{"name":"gemini-2-5-flash-mcp","command":"npx","args":["@taiyokimura/gemini-2-5-flash-mcp@latest"]}'

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "gemini-2-5-flash-mcp": {
      "type": "local",
      "command": [
        "npx",
        "@taiyokimura/gemini-2-5-flash-mcp@latest"
      ],
      "enabled": true
    }
  }
}

環境変数

• GEMINI_API_KEY (必須)
• GEMINI_IMAGE_ENDPOINT (任意) 既定値: https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-image-preview:generateContent
• MCP_NAME (任意, 既定値: gemini-2-5-flash-mcp)

💻 使用例

1. generate_image

テキストプロンプトから画像を生成します。

パラメータ:

• prompt (必須): 生成するための詳細な説明
• saveToFilePath (任意): 画像を保存するパス

入力例:

{
  "prompt": "Create a picture of a nano banana dish in a fancy restaurant with a Gemini theme",
  "saveToFilePath": "./gemini-native-image.png"
}

2. edit_image

プロンプトを使用して画像を編集します。

パラメータ:

• prompt (必須): 編集指示
• image (必須): { dataBase64?: string, path?: string, mimeType?: string }
• saveToFilePath (任意)

入力例:

{
  "prompt": "Add a small, knitted wizard hat to the cat",
  "image": { "path": "./cat.jpeg", "mimeType": "image/jpeg" },
  "saveToFilePath": "./gemini-edited-image.png"
}

3. compose_images

複数の画像から要素を合成します。

パラメータ:

• prompt (必須)
• images (必須): 画像入力の配列（2 - 3 が推奨）
• saveToFilePath (任意)

4. style_transfer

ある画像のスタイルを別の画像に転送します。

パラメータ:

• prompt (任意)
• baseImage (必須)
• styleImage (必須)
• saveToFilePath (任意)

開発

ローカルで実行するには、以下のコマンドを実行します。

npm install
npm run build
npx .

名前の一貫性とトラブルシューティング

• 識別子やキーには常にCANONICAL_ID (gemini-2-5-flash-mcp) を使用してください。
• UIラベルにのみCANONICAL_DISPLAY (Gemini 2.5 Flash MCP) を使用してください。
• クライアント間で異なる名前を混在させないでください。

一貫性マトリックス:

• npmパッケージ名 → gemini-2-5-flash-mcp
• バイナリ名 → gemini-2-5-flash-mcp
• MCPサーバー名 (SDKメタデータ) → gemini-2-5-flash-mcp
• 環境変数の既定のMCP_NAME → gemini-2-5-flash-mcp
• クライアントレジストリキー → gemini-2-5-flash-mcp
• UIラベル → Gemini 2.5 Flash MCP

競合の解消:

• "GeminiFlash" などの古いエントリを削除し、gemini-2-5-flash-mcp で再追加してください。
• グローバルレジストリではキーに gemini-2-5-flash-mcp のみを使用するようにしてください。
• Cursor: UIでのみ設定してください。このプロジェクトには .cursor/mcp.json は含まれていません。

参考資料

• MCP SDK: https://modelcontextprotocol.io/docs/sdks
• アーキテクチャ: https://modelcontextprotocol.io/docs/learn/architecture
• サーバーの概念: https://modelcontextprotocol.io/docs/learn/server-concepts
• サーバー仕様 (2025-06-18): https://modelcontextprotocol.io/specification/2025-06-18/server/index
• Gemini画像生成: https://ai.google.dev/gemini-api/docs/image-generation