ex-takashima/vertexai-imagen-mcp-server

Vertex AI Imagen MCP Server

🆕 Latest Update (v0.8.0): Runtime Validation, API Rate Limiting, Enhanced Environment Variable Support

New in v0.8.0:

• 🛡️ Runtime Validation - Comprehensive input validation with Zod for all 24 tools
• 🚦 API Rate Limiting - Prevent quota exhaustion with configurable rate limits
• ✅ Environment Variable Validation - Startup validation with helpful error messages
• 🔐 Enhanced Authentication - Full support for GOOGLE_APPLICATION_CREDENTIALS
• 📚 Documentation - New and

Vertex AI の Imagen API を使用して画像を生成・編集できる MCP（Model Context Protocol）対応サーバーです。Claude Desktop などの MCP クライアントと連携することで、チャット内から自然言語で高度な画像操作が行えます。

📚 Documentation

• - Get started in 5 minutes
• - Complete reference for all 20 environment variables
• - Version history and release notes
• - History management and metadata embedding

🌟 主な機能

画像生成・編集

• 🎨 画像生成：テキストから高品質な画像を生成
• ✨ 画像カスタマイズ：参照画像を使った高度な画像生成（構造制御、被写体一貫性、スタイル転送）
• 📝 YAML設定ファイル対応：複雑なカスタマイズパラメータをYAMLで管理、テンプレート再利用が可能
• ✂️ 高度な画像編集：AIマスク生成、セマンティック編集、背景置換対応
• 🎭 マスクなし編集：プロンプトのみで簡単に画像編集
• 🎯 5つのマスクモード：マスクフリー、手動マスク、背景自動検出、前景自動検出、セマンティック分割
• 🔄 多様な編集モード：インペイント除去、インペイント挿入、背景置換、アウトペインティング
• 📐 アスペクト比の指定：1:1, 3:4, 4:3, 9:16, 16:9 に対応
• 🔍 アップスケーリング：画像を 2 倍または 4 倍に高品質拡大
• ⚡ 統合処理：生成と拡大を一括実行

セキュリティ・品質

• 🛡️ Runtime Validation (v0.8.0+)：Zodによる包括的な入力検証（全24ツール）
• 🚦 API Rate Limiting (v0.8.0+)：設定可能なレート制限でAPI quota超過を防止
• ✅ Environment Validation (v0.8.0+)：起動時の環境変数検証で設定ミスを早期発見
• 🛡️ 安全性フィルター：安全レベルを柔軟に制御
• 👤 人物生成制御：人物の生成有無を細かく設定

管理・ユーティリティ

• 📁 画像管理：生成済み画像の一覧表示・操作
• 🏷️ セマンティッククラスID検索：画像編集用の194種類のオブジェクトクラスをカテゴリ別・キーワードで検索
• 🔗 MCP Resources API：file:// URI による効率的な画像配信（トークン消費を大幅削減）
• 🔢 自動ファイル名管理：重複時の自動連番付加で既存ファイルを保護
• 🔧 デバッグモード：ログ出力によるトラブルシュート支援

📋 前提条件

• Node.js v18 以上
• MCP 対応クライアント（例：Claude Desktop、Claude Code）

🚀 セットアップ手順

💡 Quick Start: 5分でセットアップしたい方は をご覧ください。

📚 Environment Variables: 全環境変数の詳細は を参照してください。

1. 認証方式の選択

このMCPサーバーは、3つの認証方式に対応しています：

A. API KEY認証（テスト・開発用）⭐ 推奨：初心者向け

環境変数: GOOGLE_API_KEY + GOOGLE_PROJECT_ID

メリット:

• ✅ 設定が簡単（キーファイル不要）
• ✅ Vertex AI Studioから数秒で取得可能
• ✅ テスト・プロトタイピングに最適

デメリット:

• ⚠️ 本番環境には非推奨（セキュリティ上の理由）
• ⚠️ プロジェクトIDの手動設定が必要
• ⚠️ QUOTA制限が存在する（詳細は下記参照）

⚠️ API KEY使用時のQUOTA制限について

API KEYを使用する場合、Vertex AIには**リクエスト数の上限（Quota）**が設定されています。

Quota制限エラーの例:

Quota exceeded for aiplatform.googleapis.com/online_prediction_requests_per_base_model
with base model: imagen-3.0-generate. Please submit a quota increase request.
https://cloud.google.com/vertex-ai/docs/generative-ai/quotas-genai.

対処方法:

1. Quota増加リクエスト

   • Vertex AI Quotas ページにアクセス
   • Google Cloud ConsoleでQuota増加を申請
   • プロジェクトの用途を説明して承認を待つ

2. 使用量の管理

   • 画像生成の頻度を調整
   • 不要なリトライを避ける
   • sample_count パラメータを最小限に設定

3. サービスアカウント認証への移行を検討

   • 本番環境ではサービスアカウント認証の使用を推奨
   • より高いQuotaとセキュリティが提供される

💡 ヒント: 開発・テスト時はAPI KEYで手軽に始め、本番運用時はサービスアカウント認証に切り替えることを推奨します。

B. サービスアカウント（ファイル）認証（本番環境用）✅ 推奨：本番環境

環境変数: GOOGLE_APPLICATION_CREDENTIALS（ファイルパス）

メリット:

• ✅ 本番環境推奨
• ✅ 標準的なGoogle Cloud認証方式
• ✅ より強固なセキュリティ
• ✅ プロジェクトID自動検出

デメリット:

• ⚠️ 設定がやや複雑（キーファイルのダウンロードと配置が必要）
• ⚠️ IAM権限の設定が必要

C. サービスアカウント（JSON文字列）認証（CI/CD用）

環境変数: GOOGLE_SERVICE_ACCOUNT_KEY（JSON文字列）

メリット:

• ✅ CI/CD環境に最適
• ✅ コンテナ環境で便利
• ✅ ファイルシステム不要

デメリット:

• ⚠️ JSON文字列のエスケープが必要
• ⚠️ 設定ファイルが長くなる

1-A. API KEY認証のセットアップ（推奨：初心者向け）

手順概要

1. Vertex AI Studio へアクセス
2. プロジェクトを作成または選択
3. 「Get API Key」をクリック
4. 表示されたAPI KEYをコピー
5. Google Cloud ConsoleでプロジェクトIDを確認（画面上部、プロジェクト名の横に表示）

💡 ヒント: API KEYは AIzaSy... で始まる文字列です。

設定例（Claude Desktop）

{
  "mcpServers": {
    "google-imagen": {
      "command": "vertexai-imagen-mcp-server",
      "env": {
        "GOOGLE_API_KEY": "AIzaSy...",
        "GOOGLE_PROJECT_ID": "your-project-id"
      }
    }
  }
}

🔐 注意: API KEYは機密情報です。第三者に公開しないでください。

1-B. サービスアカウント認証のセットアップ（本番環境用）

手順概要

1. Google Cloud Console へアクセス
2. プロジェクトを作成または選択
3. 「APIとサービス」→「ライブラリ」で Vertex AI API を有効化
4. 「IAMと管理」→「サービスアカウント」→「サービスアカウントを作成」
5. 名前（例：imagen-mcp-server）を入力
6. ロールは「Vertex AI ユーザー」を選択し作成
7. 作成後、「キー」タブから「新しいキーを作成」→「JSON」形式を選びダウンロード

🔐 注意：ダウンロードしたキーは厳重に保管してください。バージョン管理対象外にすることを推奨します。

2. プロジェクトのセットアップ

npm install -g @dondonudonjp/vertexai-imagen-mcp-server

# パッケージがインストールされ、使用準備完了

3. サービスアカウントキーの配置

# プロジェクト直下に配置する例
cp /path/to/key.json ./google-service-account.json

# config ディレクトリへ配置する例
mkdir -p ~/.config/google-cloud/
cp /path/to/key.json ~/.config/google-cloud/imagen-service-account.json

# アクセス制限（UNIX環境推奨）
chmod 600 ./google-service-account.json

4. インストール方法

A. NPM レジストリからインストール（推奨）

npm install -g @dondonudonjp/vertexai-imagen-mcp-server
vertexai-imagen-mcp-server --version

B. 開発リンク（npm link）

npm link
vertexai-imagen-mcp-server --version

C. Claude Desktop に直接パスを指定

{
  "mcpServers": {
    "google-imagen": {
      "command": "node",
      "args": ["C:\\projects\\vertexai-imagen-mcp-server\\build\\index.js"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "C:\\path\\to\\your\\key.json"
      }
    }
  }
}

⚙ Claude Desktop の設定

推奨設定（ファイルパスを指定）

{
  "mcpServers": {
    "google-imagen": {
      "command": "vertexai-imagen-mcp-server",
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/google-service-account.json"
      }
    }
  }
}

Windows環境ではパス区切りに注意： "C:\\Users\\User\\Documents\\key.json"

Claude Desktop の再起動

設定ファイルを保存後、Claude Desktop を完全に再起動してください（タスクトレイからも終了推奨）。

Claude Code での使用方法

Claude Code でも同様にMCPサーバーとして使用できます。

設定方法

Claude Code の設定ファイルに以下を追加してください：

{
  "mcpServers": {
    "google-imagen": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@dondonudonjp/vertexai-imagen-mcp-server"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "C:\\path\\to\\your\\google-service-account.json"
      }
    }
  }
}

macOS/Linux の場合:

{
  "mcpServers": {
    "google-imagen": {
      "command": "npx",
      "args": ["-y", "@dondonudonjp/vertexai-imagen-mcp-server"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/your/google-service-account.json"
      }
    }
  }
}

🧪 使用例（Claude 指示文）

自然言語で指示するだけで画像生成・編集・管理を行えます。 画像は自動的に ~/Downloads/vertexai-imagen-files/ に保存されます。

🟦 Ⅰ. 基本生成（Generate）

例1：シンプル生成

「美しい夕日の風景」をテーマに画像を生成し、横長の 16:9 比率でお願いします。
人物は含めず、安全性フィルターは標準（中リスク以上をブロック）で。
保存ファイル名は sunset_landscape.png としてください。

📸 出力例

例2：人物ポートレート（成人許可）

人物のポートレートを縦長（3:4）で生成してください。
成人のみ許可し、安全性フィルターは高リスクのみブロック。
保存先は portrait_adult.png にしてください。

📸 出力例

例3：英語プロンプト比較

language: "en"
Prompt: "A tranquil forest with sunbeams filtering through the trees"
保存先は forest_en.png にしてください。

📸 出力例

🟦 Ⅱ. 画像編集（Edit）

例4：背景変更（人物→森）

[reference_image_path を指定]
この人物の背景を森に置き換えてください。
mask_mode: background
edit_mode: bgswap
保存先は forest_background.png にしてください。

📸 入力画像

📸 出力例

例5：オブジェクト除去

[reference_image_path を指定]
リビングの写真からソファ上のクッションを除去してください。
mask_mode: foreground
edit_mode: inpaint_removal
保存先は clean_sofa.png にしてください。

📸 入力画像

📸 出力例

(￣□￣;)!!

例6：服装変更（セマンティック編集）

[reference_image_path を指定]
この女性の服装だけをフォーマルなビジネススーツに変更してください。顔、髪型、表情、ポーズ、背景はそのまま維持してください。紺色または黒のジャケットとパンツのスーツで、インナーは白いブラウス。プロフェッショナルで洗練された印象。
保存先は formal_outfit.pngにしてください。
mask_mode: "semantic"
mask_classes: [125] (人物)
edit_mode: "inpaint_insertion"
mask_dilation: 0.05

📸 入力画像

📸 出力例

(￣□￣;)!!

例7：マスクなし編集（Mask-Free）

[reference_image_path を指定]
この猫の写真を同じ構図で犬に変えてください。
mask_mode は指定しません。
保存先は dog_transformed.png にしてください。

📸 入力画像

📸 出力例

(￣▽￣;)

🟦 Ⅲ. カスタマイズ生成（Customize）

例8：構図制御（Control）

[reference_image_path を指定=pose.png]
pose.png のポーズを参照し、同じ構図で人物を生成してください。
control_type: "scribble"
保存先は park_woman_scribble.png にしてください。

📸 入力画像

↑ChatGPTで出力

バレエを踊っている動作を表す棒人間の写真を生成して　アスペクト比3:4　棒人間は白　背景は黒　
棒の太さは少し太め関節はよくわかるようにして

📸 出力例

↑コントロールタイプをcannyにした場合

例9：被写体一貫性（Subject）

同じ猫を別の背景で生成してください。
subject_images:
  - { image_path: "cat1.jpg" }
  - { image_path: "cat2.jpg" }
subject_description: "a brown tabby cat"
subject_type: "animal"
prompt: "An orange and white tabby cat [1] sitting on a traditional Japanese wooden engawa (veranda) in spring. Cherry blossoms visible in the background. Warm sunlight and peaceful atmosphere. Traditional Japanese house setting."
保存先は engawa_cat.png にしてください。

📸 入力画像

📸 出力例

例10：スタイル転送（Style）

style_image_path: "starry_night.png"
style_description: "Van Gogh painting style with swirling brushstrokes"
prompt: "A modern city skyline at night with tall skyscrapers, illuminated windows, and city lights reflected in water, painted in the style of [1]. Swirling sky with stars above the buildings."
output_path: "van_gogh_city_detailed.png"

📸 入力画像

📸 出力例

例11：複合利用（被写体＋構図＋スタイル）

{
  `prompt`: `A Renaissance oil painting portrait of a young Japanese woman [1] in an elegant dynamic pose with one arm raised gracefully [2]. She wears luxurious Renaissance-era clothing with rich fabrics, jewelry, and period-appropriate accessories. Painted in the classical Renaissance style [3] with chiaroscuro lighting, warm golden tones, detailed brushwork, and a dark background. The pose should match the reference gesture while maintaining the dignified Renaissance portrait aesthetic.`,
  `language`: `en`,
  `output_path`: `renaissance_pose_detailed.png`,
  `aspect_ratio`: `1:1`,
  `control_type`: `scribble`,
  `subject_type`: `person`,
  `subject_images`: [
    {
      `woman_park_1x1.png`
    }
  ],
  `style_image_path`: `renaissance_1x1.png`,
  `person_generation`: `ALLOW_ADULT`,
  `style_description`: `Renaissance oil painting style with chiaroscuro lighting and rich colors`,
  `control_image_path`: `pose1x1.png`,
  `subject_description`: `A young Japanese woman in her 20s with natural features and a friendly expression`,
  `enable_control_computation`: false
}

📸 入力画像

📸 出力例

( ･_･;)

🟦 Ⅳ. 高解像度・統合処理

例12：生成＋アップスケーリング

ドラゴンのイラストを横長 16:9 で生成し、4倍に拡大して保存してください。
generate_and_upscale_image を使い、
出力ファイル名は dragon_4x.png にしてください。

📸 出力例

例13：既存画像のアップスケーリング

input_path: "portrait_adult.png"
scale_factor: 4
保存ファイル名は portrait_upscaled.png にしてください。

🟦 Ⅴ. 管理・ユーティリティ

例14：生成画像一覧

保存ディレクトリ内の生成画像を一覧表示してください。
list_generated_images

例15：セマンティッククラス検索

「動物」カテゴリのセマンティッククラスを表示してください。
list_semantic_classes

例16：file:// URI 確認

青空の風景を生成し、出力パスを教えてください。

📄 返却例： file:///Users/username/Downloads/vertexai-imagen-files/sky.png

例17：サムネイル生成有効化

「桜並木の風景」を生成して、サムネイルも作成してください。
include_thumbnail: true

💡 VERTEXAI_IMAGEN_THUMBNAIL=true を設定すると、すべての生成で自動的にサムネイルが生成されます。

注意 Claude Desktopで有効にするとチャットが中断されます

🛠 利用可能な MCP ツール

1. generate_image

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

• prompt（必須）: テキストプロンプト
• output_path: 保存ファイル名（省略可）
• aspect_ratio: 画像比率（例: 1:1, 16:9）
• return_base64: 非推奨 Base64で返却（デフォルト: false）
• include_thumbnail: サムネイル生成（128x128、約30-50トークン）。未指定時は環境変数 VERTEXAI_IMAGEN_THUMBNAIL の設定に従う
• safety_level: 安全性フィルター（BLOCK_NONE〜BLOCK_LOW_AND_ABOVE）
• person_generation: 人物生成ポリシー（DONT_ALLOW, ALLOW_ADULT, ALLOW_ALL）
• language: プロンプト処理言語（auto, en, ja, ko など、デフォルト: auto）
• model: 使用するImagenモデル（デフォルト: imagen-3.0-generate-002）

2. edit_image - 高度な画像編集

Imagen 3.0対応の高度な画像編集機能。AIによる自動マスク生成、セマンティック分割、多様な編集モードに対応します。

基本パラメータ

• prompt（必須）: 編集内容の説明
• reference_image_base64 / reference_image_path: 元画像（どちらか必須）
• output_path: 保存ファイル名（省略可、デフォルト: edited_image.png）
• return_base64: 非推奨 Base64で返却（デフォルト: false）
• include_thumbnail: サムネイル生成（128x128、約30-50トークン）。未指定時は環境変数 VERTEXAI_IMAGEN_THUMBNAIL の設定に従う

マスク指定方法（5つの選択肢）

🔹 マスクなし編集（Mask-Free）⭐ NEW!

mask_mode: "mask_free"  # または mask_mode を未指定
# プロンプトのみで編集領域と内容をAIが自動判断

特徴:

• マスクを一切指定しない最もシンプルな編集方法
• プロンプトで「猫を犬に変える」「背景を森に変える」などと指示するだけで編集可能
• AIが画像全体を解釈して自動的に適切な領域を編集
• 手軽さと柔軟性を両立

🔹 手動マスク（従来の方法）

mask_mode: "user_provided"
mask_image_base64 / mask_image_path: 白=編集対象、黒=保持領域

🔹 背景自動マスク

mask_mode: "background"  # 背景を自動検出してマスク生成

🔹 前景自動マスク

mask_mode: "foreground"  # 前景（主要被写体）を自動検出

🔹 セマンティックマスク

mask_mode: "semantic"
mask_classes: [125]  # 人物のクラスID（必須）

編集モード

• edit_mode: 編集タイプ
  • "inpaint_insertion": コンテンツの追加・修正（デフォルト）
  • "inpaint_removal": コンテンツの除去
  • "bgswap": 背景置換
  • "outpainting": キャンバス拡張（画像を元のサイズより大きく拡張）

高度なパラメータ

• mask_dilation: マスク境界の拡張量（0.01-0.1、デフォルト: 0.01）
• base_steps: サンプリングステップ数（1-75、除去は12-20、挿入は最大75推奨）
• guidance_scale: プロンプトの強さ（0〜30）
• negative_prompt: 回避したい要素の指示
• mask_classes: セマンティックマスク用クラスID配列
• model: 使用する Imagen 編集モデル（デフォルト: imagen-3.0-capability-001）

📋 編集パラメータ詳細リファレンス

🎯 推奨設定組み合わせ

3. customize_image - 参照画像を使った高度な画像カスタマイズ ⭐ NEW!

Imagen 3.0対応の参照画像を使った画像生成機能。構造制御、被写体一貫性、スタイル転送に対応します。

基本パラメータ

• prompt（必須）: 画像生成のプロンプト（[1], [2]などで参照画像IDを指定可能）
• output_path: 保存ファイル名（省略可、デフォルト: customized_image.png）
• aspect_ratio: 画像比率（例: 1:1, 16:9、デフォルト: 1:1）
• return_base64: 非推奨 Base64で返却（デフォルト: false）
• include_thumbnail: サムネイル生成（128x128、約30-50トークン）

参照画像タイプ（少なくとも1つ必須）

🎮 構造制御（Control）

画像の構造・ポーズ・構図を制御します。

control_image_path: "pose.png"  # または control_image_base64
control_type: "face_mesh" | "canny" | "scribble"
enable_control_computation: true  # true=自動計算（推奨、通常の画像）、false=処理済み画像使用（デフォルト: true）

control_type の種類:

• "face_mesh": 顔メッシュ（人物のポーズ制御）
• "canny": Cannyエッジ検出（輪郭・構造制御）
• "scribble": フリーハンド描画（ラフな構図指定）

使用例:

プロンプト: "A portrait of a person [1] in a professional pose"
control_image_path: "pose_reference.jpg"
control_type: "face_mesh"
→ 参照画像[1]のポーズを保ちながら新しい人物を生成

👤 被写体一貫性（Subject）

同じ被写体を一貫して生成します。複数の参照画像で精度向上。

subject_images: [
  { image_path: "person1.jpg" },
  { image_path: "person2.jpg" }  # 複数指定で品質向上
]
subject_description: "a man with short hair"  # 必須（被写体の説明）
subject_type: "person" | "animal" | "product" | "default"  # 必須

subject_type の種類:

• "person": 人物
• "animal": 動物
• "product": 商品
• "default": その他の被写体

使用例:

プロンプト: "A photo of [1] at the beach"
subject_images: [
  { image_path: "cat_photo1.jpg" },
  { image_path: "cat_photo2.jpg" }
]
subject_description: "a brown tabby cat"
subject_type: "animal"
→ 同じ猫をビーチで撮影したような画像を生成

🎨 スタイル転送（Style）

参照画像のスタイルを適用します。

style_image_path: "art_style.jpg"  # または style_image_base64
style_description: "Van Gogh painting style"  # 省略可（推奨：記述することで精度向上）

使用例:

プロンプト: "A landscape in the style of [1]"
style_image_path: "starry_night.jpg"
style_description: "Van Gogh's impressionist style"
→ ゴッホ風の風景画を生成

複合利用

複数の参照タイプを同時に使用できます：

プロンプト: "A portrait of [1] in the pose of [2] with the style of [3]"
subject_images: [{ image_path: "person.jpg" }]
subject_description: "a woman with long hair"
subject_type: "person"
control_image_path: "pose.jpg"
control_type: "face_mesh"
style_image_path: "painting.jpg"
style_description: "Renaissance painting style"
→ 特定の人物を、指定されたポーズで、ルネサンス風に描画

その他パラメータ

• safety_level: 安全性フィルター（BLOCK_NONE〜BLOCK_LOW_AND_ABOVE）
• person_generation: 人物生成ポリシー（DONT_ALLOW, ALLOW_ADULT, ALLOW_ALL）
• language: プロンプト処理言語（auto, en, ja, ko など、デフォルト: auto）
• negative_prompt: 回避したい要素の指示
• model: 使用するImagenモデル（デフォルト: imagen-3.0-generate-002）

📋 参照画像ID について

プロンプト内で [1], [2], [3] などを使用して、各参照画像を参照できます：

• Control画像が最初に提供された場合 → [1]
• Subject画像が最初に提供された場合 → [1]（複数の被写体画像は同じIDを共有）
• Style画像が最初に提供された場合 → [1]

複数タイプを組み合わせる場合、追加順に番号が割り当てられます。

4. customize_image_from_yaml - YAML設定ファイルから画像カスタマイズ ⭐ NEW!

複雑な customize_image のパラメータをYAML設定ファイルで管理できます。テンプレートを再利用したり、複数の参照画像を整理して指定できます。

基本パラメータ

• yaml_path（必須）: YAML設定ファイルのパス（絶対パスまたは相対パス）

YAML設定ファイルの構造

YAML設定ファイルには、customize_image ツールのすべてのパラメータを記述できます：

# 基本設定（必須）
model: "imagen-3.0-capability-001"
output_path: "./output/my_image.png"
prompt: "A portrait of [1] in the style of [2]"

# 参照画像設定
subjects:
  - reference_id: 1
    images:
      - "./images/person1.jpg"
      - "./images/person2.jpg"
    config:
      type: "person"
      description: "a young woman with long hair"  # 必須

style:
  reference_id: 2
  image_path: "./images/art_style.jpg"
  description: "impressionist painting style"  # 省略可能

# その他のパラメータ
aspect_ratio: "3:4"
sample_count: 2
safety_level: "BLOCK_MEDIUM_AND_ABOVE"

使用例

templates/customize/04_with-style.yaml の設定で画像を生成してください

サンプルテンプレート

このリポジトリには以下のサンプルテンプレートが含まれています：

• templates/customize/01_subject-only.yaml - 被写体のみ（最小構成）
• templates/customize/02_multi-subject.yaml - 複数被写体
• templates/customize/03_with-control.yaml - 制御画像（構造制御）
• templates/customize/04_with-style.yaml - スタイル画像（スタイル転送）
• templates/customize/05_full-featured.yaml - 全機能統合（被写体+制御+スタイル）

詳細な説明とYAML形式のリファレンスは を参照してください。

メリット

• ✅ 再利用性: 同じ設定を何度も使用可能
• ✅ 可読性: 複雑なパラメータをわかりやすく整理
• ✅ バージョン管理: YAML設定をGitで管理
• ✅ テンプレート化: プロジェクトごとにテンプレートを用意
• ✅ コメント: パラメータの説明をコメントとして記述可能

YAML設定の詳細

YAML形式で指定できるすべてのパラメータと検証ルールについては、以下を参照してください：

📖

• YAML構造の詳細説明
• reference_id のルール
• パス指定方法
• トラブルシューティング

4-2. customize_image_from_yaml_inline - インラインYAMLから画像カスタマイズ ⭐ NEW!

YAMLファイルの代わりに、YAML内容を文字列として直接チャットに貼り付けて画像をカスタマイズできます。customize_image_from_yaml と同じ機能ですが、ファイルパス指定が不要で、より手軽に使用できます。

基本パラメータ

• yaml_content（必須）: YAML設定内容（文字列）

YAML内容の構造

YAML内容は customize_image_from_yaml と同じ構造です。以下のすべてのパラメータを記述できます：

# 基本設定（必須）
model: "imagen-3.0-capability-001"
output_path: "./output/my_image.png"
prompt: "A portrait of [1] in the style of [2]"

# 参照画像設定
subjects:
  - reference_id: 1
    images:
      - "./images/person1.jpg"
      - "./images/person2.jpg"
    config:
      type: "person"
      description: "a young woman with long hair"  # 必須

style:
  reference_id: 2
  image_path: "./images/art_style.jpg"
  description: "impressionist painting style"  # 省略可能

# その他のパラメータ
aspect_ratio: "3:4"
sample_count: 2
safety_level: "BLOCK_MEDIUM_AND_ABOVE"

使用例

以下のYAML設定で画像を生成してください：

model: "imagen-3.0-capability-001"
output_path: "portrait_style.png"
prompt: "A portrait of [1] in the style of [2]"

subjects:
  - reference_id: 1
    images:
      - "woman_photo.jpg"
    config:
      type: "person"
      description: "a young woman with long hair"

style:
  reference_id: 2
  image_path: "art_style.jpg"
  description: "impressionist painting style"

aspect_ratio: "3:4"

ファイルパスとインラインYAMLの使い分け

メリット

• ✅ ファイル不要: YAMLファイルを作成せずに直接実行
• ✅ チャット内で編集: 設定をその場で調整可能
• ✅ 共有が簡単: YAML内容をコピー&ペーストで共有
• ✅ テスト実行: 設定を試す際に便利

注意事項

• YAML構文エラーがある場合、適切なエラーメッセージが表示されます
• ファイルパスは customize_image_from_yaml と同じルールで解決されます
• 同じYAML設定を繰り返し使用する場合は、customize_image_from_yaml でファイル保存することを推奨

5. upscale_image

画像を 2 倍 / 4 倍にアップスケールします。

• input_path（必須）: 入力ファイルパス
• output_path: 保存ファイル名（省略可）
• scale_factor: 倍率（デフォルト: 2）
• return_base64: 非推奨 Base64で返却（デフォルト: false）
• include_thumbnail: サムネイル生成（128x128、約30-50トークン）。未指定時は環境変数 VERTEXAI_IMAGEN_THUMBNAIL の設定に従う

5. generate_and_upscale_image

画像生成とアップスケーリングを一括で行います。 generate_image と upscale_image の統合処理です。

• prompt（必須）: テキストプロンプト
• output_path: 保存ファイル名（省略可）
• aspect_ratio: 画像比率（例: 1:1, 16:9）
• scale_factor: 倍率（デフォルト: 2）
• return_base64: 非推奨 Base64で返却（デフォルト: false）
• include_thumbnail: サムネイル生成（128x128、約30-50トークン）。未指定時は環境変数 VERTEXAI_IMAGEN_THUMBNAIL の設定に従う
• safety_level: 安全性フィルター（BLOCK_NONE〜BLOCK_LOW_AND_ABOVE）
• person_generation: 人物生成ポリシー（DONT_ALLOW, ALLOW_ADULT, ALLOW_ALL）
• language: プロンプト処理言語（auto, en, ja, ko など、デフォルト: auto）
• model: 使用するImagenモデル（デフォルト: imagen-3.0-generate-002）

6. list_generated_images

ディレクトリ内の画像ファイルを一覧表示します。

• directory: 検索対象フォルダ（省略時はカレントディレクトリ）

7. list_semantic_classes - セマンティッククラスID検索 ⭐ NEW!

Imagen 3.0対応のセマンティック分割用クラスID（0-193の全194クラス）を検索・一覧表示します。 edit_image の mask_mode: "semantic" で使用する mask_classes パラメータに指定するクラスIDを簡単に見つけられます。

パラメータ（すべて省略可）

• category: カテゴリで絞り込み（例: "人物", "動物", "乗り物", "家具", "電化製品", "食品", "建物・構造", "自然", "屋外設備", "スポーツ用品", "アクセサリー", "その他"）
• search: 日本語または英語でキーワード検索（例: "車", "car", "人", "person"）
• ids: 特定のクラスIDの詳細情報を取得（例: [125, 175, 176]）

使用例

全クラス一覧表示

セマンティッククラスの一覧を教えてください

カテゴリで絞り込み

「動物」カテゴリのセマンティッククラスを教えてください

キーワード検索

セマンティッククラスで「車」に関連するものを検索してください

特定IDの詳細確認

セマンティッククラスID 125, 175, 176 の詳細を教えてください

出力形式

全一覧表示の場合:

• よく使われるクラスIDをハイライト表示
• 全クラスをカテゴリ別にグループ化して表示
• 各クラスのID、日本語名、英語名を表示

検索結果の場合:

• マッチしたクラスのみを表示
• ID、日本語名、英語名を含む詳細情報

特定ID検索の場合:

• 指定されたIDのクラス情報を詳細表示
• カテゴリ情報も含む
• edit_imageでの使用方法のヒントを表示

💡 使い方のヒント

このツールで見つけたクラスIDは、edit_image ツールの mask_classes パラメータに指定して使用します：

# 例: 人物（ID: 125）を編集対象にする
mask_mode: "semantic"
mask_classes: [125]

# 例: 複数のオブジェクトを対象にする（自転車と車）
mask_mode: "semantic"
mask_classes: [175, 176]

利用可能なImagenモデル

使用例:

プロンプト: "美しい山の風景"
モデル: imagen-4.0-ultra-generate-preview-06-06

編集・アップスケール用モデル

🏷️ セマンティックマスク対応クラスID（公式ドキュメント準拠）

画像編集でmask_mode: "semantic"を使用する際の代表的なクラスIDです：

⚠️ 重要: 複数のオブジェクトを対象にする場合は配列で指定（例: [7, 8] で猫と犬）

💡 ヒント: 完全なクラスID一覧（全194クラス、ID: 0-193）は list_semantic_classes ツールで検索・確認できます。カテゴリ別表示、キーワード検索、特定ID検索に対応しています。詳細はVertex AI Imagen API公式ドキュメントも参照してください。

プロンプトの言語について

省略可。テキスト プロンプト言語に対応する言語コード。サポートされる値は次のとおりです。

• auto: 自動検出。Imagen がサポートされている言語を検出すると、プロンプトとオプションの否定的なプロンプトが英語に翻訳されます。検出された言語がサポートされていない場合、Imagen は入力テキストをそのまま使用するため、予期しない出力になる可能性があります。エラーコードは返されません。
• en: 英語
• ja: 日本語
• ko: 韓国語
• zh: 中国語（簡体）
• zh-tw: 中国語（繁体）
• hi: ヒンディー語
• pt: ポルトガル語
• es: スペイン語

🧪 開発・テスト

npm run dev         # 開発モード
DEBUG=1 npm run dev # デバッグモード（詳細ログあり）

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

🔧 画像編集関連トラブルシューティング

📖 コマンドラインと環境変数

vertexai-imagen-mcp-server --help
vertexai-imagen-mcp-server --version

📚 Complete Reference: すべての環境変数の詳細は を参照してください。

主要な環境変数

新機能（v0.8.0+）

🛡️ Runtime Validation

すべてのツール入力を起動時に検証し、不正なパラメータを事前に検出します。

🚦 API Rate Limiting

{
  "env": {
    "VERTEXAI_RATE_LIMIT_MAX_CALLS": "60",
    "VERTEXAI_RATE_LIMIT_WINDOW_MS": "60000"
  }
}

設定例：60回/分（1分あたり最大60回のAPI呼び出し）

✅ Environment Variable Validation

起動時に全環境変数を自動検証：

• 認証方法の確認
• 数値範囲のチェック
• JSONフォーマット検証
• 明確なエラーメッセージとセットアップガイド表示

📜 履歴管理・メタデータ機能

このMCPサーバーは、生成した画像の履歴を自動的に記録し、後から検索・参照できる強力な履歴管理機能を提供します。

主な機能

• ✅ 自動履歴記録: すべての画像生成をSQLiteデータベースに自動保存
• ✅ UUID追跡: 各画像に一意のUUIDを割り当て、画像とデータベースを紐付け
• ✅ メタデータ埋め込み: 画像ファイル自体にUUIDや生成パラメータを埋め込み（PNG/JPEG/WebP対応）
• ✅ フルテキスト検索: プロンプトやパラメータで高速検索
• ✅ 整合性検証: ハッシュ値による画像の改ざん検出

履歴管理ツール

使用例

# 最近の履歴を表示
「最近生成した画像の履歴を10件表示してください」

# キーワードで検索
「"sunset"というキーワードで画像を検索して」

# 画像からメタデータを読み取る
「sunset.pngに埋め込まれたメタデータを読み取って」

# 特定のUUIDで詳細確認
「UUID abc123... の画像の詳細情報を教えて」

詳細ドキュメント

履歴機能の詳細については、以下のドキュメントを参照してください：

📖

• 環境変数の詳細説明
• メタデータ埋め込みの仕組み
• データベーススキーマ
• トラブルシューティング
• ベストプラクティス

📁 ファイル保存パスについて

デフォルトの保存先

このMCPサーバーは、Claude DesktopなどのMCPクライアントがコンテナ環境で動作することを考慮し、クロスプラットフォーム対応のパス処理を実装しています。

デフォルト保存先: ~/Downloads/vertexai-imagen-files/

• macOS: /Users/username/Downloads/vertexai-imagen-files/
• Windows: C:\Users\username\Downloads\vertexai-imagen-files\
• Linux: /home/username/Downloads/vertexai-imagen-files/

パス指定の方法

1. 相対パスを指定（推奨）

# デフォルトディレクトリ配下に保存される
output_path: "my_image.png"
→ ~/Downloads/vertexai-imagen-files/my_image.png

# サブディレクトリも自動作成される
output_path: "animals/cat.png"
→ ~/Downloads/vertexai-imagen-files/animals/cat.png

2. 絶対パスを指定

# 絶対パスはそのまま使用される
output_path: "/Users/username/Desktop/image.png"
→ /Users/username/Desktop/image.png

# Windowsの場合
output_path: "C:\\Users\\username\\Pictures\\image.png"
→ C:\Users\username\Pictures\image.png

3. 環境変数でカスタマイズ

{
  "mcpServers": {
    "google-imagen": {
      "command": "vertexai-imagen-mcp-server",
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/key.json",
        "VERTEXAI_IMAGEN_OUTPUT_DIR": "/Users/username/MyImages"
      }
    }
  }
}

この設定により、相対パスは /Users/username/MyImages/ 配下に保存されます。

自動機能

✅ 親ディレクトリの自動作成: 指定されたパスの親ディレクトリが存在しない場合、自動的に作成されます ✅ パス検証: API呼び出し前にパスを検証するため、APIクォータの無駄遣いを防止 ✅ ファイル名重複チェック: 同名ファイルが存在する場合、自動的に連番を付加（例: image.png → image_1.png → image_2.png） ✅ ユーザーフレンドリーな表示: 保存先は ~ 表記で表示されます（例: ~/Downloads/vertexai-imagen-files/image.png）

ファイル名重複の自動処理

同じファイル名で複数回画像を生成した場合、既存ファイルを保護するため自動的に連番が付加されます：

# 1回目の生成
output_path: "landscape.png"
→ ~/Downloads/vertexai-imagen-files/landscape.png

# 2回目の生成（同じファイル名）
output_path: "landscape.png"
→ ~/Downloads/vertexai-imagen-files/landscape_1.png

# 3回目の生成
output_path: "landscape.png"
→ ~/Downloads/vertexai-imagen-files/landscape_2.png

この機能により、既存の画像ファイルが誤って上書きされるリスクがなくなります。

📥 入力画像パスの扱い（edit_image / upscale_image）

v0.5.0から改善: 入力画像パス（reference_image_path, mask_image_path, input_path）も出力パスと同様の解決方法を採用しました。

パス解決ルール

# ✅ 相対パス指定（推奨）
reference_image_path: "street_wires.png"
→ ~/Downloads/vertexai-imagen-files/street_wires.png から読み込み

# ✅ 絶対パス指定
reference_image_path: "C:\\Users\\username\\Pictures\\image.png"
→ 指定されたパスそのままから読み込み

# ❌ チルダ記法は非対応
reference_image_path: "~/Downloads/image.png"
→ エラー（展開されません）

推奨ワークフロー

1. 生成: generate_image で相対パス指定 → VERTEXAI_IMAGEN_OUTPUT_DIRに保存
2. 編集: 同じファイル名を相対パスで指定 → 自動的に同じディレクトリから読み込み

# 例: 画像生成 → 編集のワークフロー
1. generate_image → output_path: "cat.png"
   保存先: ~/Downloads/vertexai-imagen-files/cat.png

2. edit_image → reference_image_path: "cat.png"
   読み込み元: ~/Downloads/vertexai-imagen-files/cat.png（自動解決）

トラブルシューティング

エラー: "Reference image file could not be read from path: ..."

• 相対パスの場合、VERTEXAI_IMAGEN_OUTPUT_DIR（デフォルト: ~/Downloads/vertexai-imagen-files/）からの相対パスとして解釈されます
• 異なる場所の画像を使用する場合は、絶対パスで指定してください
• list_generated_images ツールで現在のディレクトリを確認できます

⚡ パフォーマンスとベストプラクティス

🖼️ 画像返却モードの選択

このMCPサーバーは2つの画像返却モードをサポートしています：

1. ファイル保存モード（推奨）✅

return_base64: false  # デフォルト

メリット:

• ⚡ トークン消費が少ない: MCPプロトコルでの通信量を大幅削減
• 📁 ファイル管理が容易: 生成した画像をローカルファイルとして保存
• 💾 大きな画像も扱える: サイズ制限を気にせず高解像度画像を生成可能
• 🔄 再利用が簡単: 保存されたファイルを他のツールでも使用可能

推奨される用途:

• 通常の画像生成
• アップスケーリング（高解像度化）
• 本番環境での使用
• 複数画像の生成

2. Base64返却モード

return_base64: true

デメリット:

• ⚠️ トークン消費が大きい: 1画像あたり約1,500トークン消費（約1,000語相当）
• 📏 サイズ制限: MCPプロトコルでは1MB未満推奨
• 🐌 通信量増加: Base64エンコードにより元のサイズの約133%に増加
• 💬 会話履歴の圧迫: 長時間の会話でコンテキストを消費

注意事項:

このモードを使用すると、生成画像がBase64文字列としてMCPレスポンスに含まれるため、大量のトークンを消費します。 annotations.audience: ["user"] により画像はLLMのコンテキストからは除外されますが、MCPクライアントへの転送時のトークン消費は削減できません。

限定的な用途:

• 一時的なプレビュー表示
• テスト・デモンストレーション
• ファイルシステムアクセスが制限される特殊な環境

📊 モード比較表

💡 推奨事項

✅ ファイル保存モードを使用する場合（推奨）:

# 指示例
「美しい夕日の風景を生成して、sunset.pngとして保存してください」

⚠️ Base64モードは避ける:

# 非推奨の指示例
「return_base64をtrueにして生成してください」
→ トークン消費が大きいため、特別な理由がない限り使用しないでください

🔍 MCP Resources API（v0.4.0+）

✅ 実装済み：このサーバーは MCP Resources API に完全対応しています。

Model Context Protocolの仕様に準拠し、以下の機能を提供：

• file:// URIによる画像配信: 生成された画像は自動的に file:// URI として返却
• リソース一覧取得: resources/list エンドポイントで全生成画像を列挙
• オンデマンド取得: resources/read エンドポイントで画像データを必要時のみ取得
• トークン効率化: 画像データはURI参照のみで返却されるため、約1,500トークン/画像を削減

利用方法

ファイル保存モード（デフォルト）を使用すると、自動的にResources API経由で画像が提供されます：

# 画像生成後、以下の情報が返却されます:
✅ file:// URI（例: file:///Users/username/Downloads/vertexai-imagen-files/sunset.png）
✅ MCP Resources APIで参照可能
✅ トークン消費を最小化

📚 参考: MCP Specification - Resources

Base64モードの非推奨化

⚠️ 重要: return_base64=true オプションは v1.0.0で削除予定 です。

• 現在は互換性のため維持されていますが、使用は推奨されません
• Resources API を使用したfile:// URI配信が標準となります
• 既存のBase64モード利用者は、ファイル保存モードへの移行を推奨

🖼️ サムネイル機能（オプション）

✨ 新機能: 画像プレビュー用のサムネイル自動生成に対応しました。

機能概要

ファイル保存モードで画像を生成する際、オプションで小さなサムネイル画像を生成し、即座にプレビュー表示できます。

有効化方法

方法1: 環境変数で全体的に有効化（推奨）

{
  "mcpServers": {
    "google-imagen": {
      "command": "vertexai-imagen-mcp-server",
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/key.json",
        "VERTEXAI_IMAGEN_THUMBNAIL": "true"
      }
    }
  }
}

方法2: ツール呼び出し時に個別指定

# サムネイル有効で生成
include_thumbnail: true

# サムネイル無効で生成
include_thumbnail: false

# 未指定の場合は環境変数の設定に従う

トークン消費

サムネイル仕様

• サイズ: 最大128×128ピクセル（アスペクト比維持）
• 品質: JPEG品質60
• 追加トークン消費: 約30-50トークン/画像
• 処理時間: 約5-30ms（画像サイズによる）

技術的詳細

• Sharp ライブラリによる高速・高品質な画像処理
• アスペクト比を維持したリサイズ
• 元画像より大きくしない制御
• サムネイル生成失敗時も本処理は継続（エラー非表示）

使用例

# 環境変数で有効化後
「美しい夕日の風景を生成してください」

→ file:// URI で高解像度画像を提供
→ 同時に128×128のサムネイルも表示（即座にプレビュー可能）

注意事項

⚠️ Claude Desktopのトークン制限: 1回の会話でメッセージ最大文字数に達する場合があります。その場合は以下のいずれかの対応を推奨：

• サムネイルを無効化（VERTEXAI_IMAGEN_THUMBNAIL を設定しない、またはデフォルトのまま）
• 新しいチャットを開始
• file:// URI経由でフル画像にアクセス（MCP Resources API経由）

💡 推奨: 通常の使用では**サムネイル無効（デフォルト）**で十分です。file:// URIでフル画像に即座にアクセスできます。

🔒 セキュリティ上の注意点

• サービスアカウントキーは .gitignore に追加し、公開しないでください
• 最小権限の原則に従い、Vertex AI ユーザー 権限のみを付与
• 不要なキーは即削除し、必要に応じて定期的にローテーションしてください

💰 料金について

Vertex AI の Generative AI モデルの一部を利用しており、従量課金制です。

• 最新の価格は以下を参照してください：
  https://cloud.google.com/vertex-ai/generative-ai/pricing?hl=ja

• 価格例（2025年7月時点、変更される可能性あり）:

  • Imagen 3（画像生成）: 約 $0.040 / 画像
  • アップスケーリング処理も別途課金対象となる場合があります

無料枠について

• Google Cloud 無料トライアル：新規アカウントに $300 クレジット（90日間）付与
• Vertex AI 自体には常設の無料枠はありません

⚠️ 実際の料金やリージョンごとの価格変動、課金単位などは必ず公式サイトでご確認ください。

🤝 コントリビューション歓迎

1. リポジトリをフォーク
2. ブランチを作成（例: feature/add-func）
3. 変更をコミット・プッシュ
4. プルリクエストを送信

📄 ライセンス

MIT License（詳細は LICENSE ファイルを参照）

🙏 謝辞

• Model Context Protocol
• Google Cloud Vertex AI Imagen