Gemini Image Generation MCP

Gemini 画像・動画生成 MCP

Claude やその他の LLM が Google の Gemini AI モデル（Gemini 2.0 Flash および Veo 2.0）を使用して画像や動画を生成できる、プロダクション対応の Model Context Protocol（MCP）サーバーです。

🌟 機能

主な機能

• ✨ 画像生成 - Gemini 2.0 Flash（gemini-2.0-flash-preview-image-generation）を使用して画像を作成します
• 🎬 動画生成 - Veo 2.0（veo-2.0-generate-001）を使用して動画を生成します
• 🎨 画像から動画を生成 - Veo 2.0 で画像を動画にアニメーション化します
• 💾 ローカルストレージ - 生成したコンテンツを自動的に保存します
• ⚙️ パラメーター制御 - temperature、topK、topP を微調整します

プロダクション向け機能

• 🔒 任意の認証 - トークンベースの API セキュリティ
• ⚡ レスポンスキャッシュ - 繰り返しのプロンプトを対象とした 30 分の TTL キャッシュ
• 📊 レート制限 - API の不正利用を防止します（全般：15 分あたり 100 件、生成：15 分あたり 20 件）
• ✅ 入力検証 - 包括的なリクエスト検証
• 📄 ページネーション - 並べ替え機能付きでギャラリーを効率的に閲覧できます
• 🔐 設定可能な CORS - 環境変数に基づいてオリジンを制御します
• 📚 OpenAPI ドキュメント - /api-docs でインタラクティブな Swagger UI を利用できます
• 🧪 テストスイート - Jest による 17 件の自動テスト
• 🐳 Docker サポート - コンテナ化された環境へ簡単にデプロイできます

📋 前提条件

• Node.js 18 以降
• 以下へのアクセス権を持つ Google API キー：
  • Gemini 2.0 Flash（画像生成）
  • Veo 2.0（動画生成）
• Docker（任意。コンテナ化された環境へのデプロイに使用）

🚀 クイックスタート

インストール

# Clone the repository
git clone https://github.com/your-org/gemini-image-gen-mcp.git
cd gemini-image-gen-mcp

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env and add your GEMINI_API_KEY

サーバーの起動

オプション 1：Node.js（開発）

# MCP server only (for Claude integration)
npm start

# Web server with REST API + UI
npm run web

# Or use the start script
./start-server.sh --both      # Both servers
./start-server.sh --mcp-only  # MCP only
./start-server.sh --web-only  # Web only

オプション 2：Docker（本番環境）

docker-compose up -d

ウェブインターフェースは http://localhost:3070 で利用できます

🎯 API エンドポイント

生成エンドポイント

• POST /api/generate-image - テキストプロンプトから画像を生成します
• POST /api/generate-video - テキストプロンプトから動画を生成します
• POST /api/generate-video-from-image - 初期画像から動画を生成します

ギャラリーエンドポイント

• GET /api/images?page=1&limit=20 - 生成した画像を一覧表示します（ページネーション対応）
• GET /api/videos?page=1&limit=20 - 生成した動画を一覧表示します（ページネーション対応）

システムエンドポイント

• GET /health - ヘルスチェック
• GET /api-docs - インタラクティブな Swagger UI ドキュメント
• GET /api-docs.json - OpenAPI JSON 仕様
• GET /api/cache/stats - キャッシュの統計情報を表示します
• POST /api/cache/clear - レスポンスキャッシュをクリアします（認証が必要）

📖 API ドキュメント

インタラクティブな API ドキュメントは以下で利用できます：

• Swagger UI：http://localhost:3070/api-docs
• OpenAPI JSON：http://localhost:3070/api-docs.json

Swagger UI では以下を利用できます：

• すべてのエンドポイントのドキュメント
• リクエスト／レスポンスのスキーマ
• その場で試せる機能
• 認証のテスト
• パラメーターの説明と例

🔐 認証

認証は任意です。API_AUTH_TOKEN 環境変数を設定すると有効になります：

# In .env file
API_AUTH_TOKEN=your-secure-token-here

認証の使用

Bearer トークン（推奨）：

curl -H "Authorization: Bearer your-secure-token-here" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A sunset over mountains"}' \
  http://localhost:3070/api/generate-image

クエリパラメーター（代替方法）：

curl -X POST \
  "http://localhost:3070/api/generate-image?token=your-secure-token-here" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A sunset over mountains"}'

⚙️ 設定オプション

.env 内の環境変数ですべての設定を行います：

変数	説明	デフォルト
GEMINI_API_KEY	必須 - Google Gemini API キー	-
API_AUTH_TOKEN	任意 - API 認証トークン	-
MCP_AUTH_TOKEN	任意 - MCP サーバーの認証トークン	-
PORT	ウェブサーバーのポート	3070
OUTPUT_DIR	生成ファイルのベースディレクトリ	./generated-images
LOG_LEVEL	ログレベル（debug、info、warn、error）	info
CORS_ORIGINS	許可するオリジン（カンマ区切り）	*
RATE_LIMIT_MAX	IP ごとの 15 分あたりの最大リクエスト数	100
GENERATION_RATE_LIMIT	15 分あたりの生成リクエストの最大数	20
ENABLE_CACHE	レスポンスキャッシュを有効にするかどうか	true

🧪 テスト

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage report
npm run test:coverage

現在のテストカバレッジ：

• 2 つのテストスイート
• 17 件のテストに合格
• カバレッジ対象：認証、ツールスキーマ、入力検証

🐳 Docker によるデプロイ

Docker Compose の使用（推奨）

# Start services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Docker の手動ビルド

# Build image
docker build -t gemini-image-gen-mcp .

# Run container
docker run -d \
  -p 3070:3070 \
  -e GEMINI_API_KEY=your_key_here \
  -v $(pwd)/generated-images:/app/generated-images \
  -v $(pwd)/generated-videos:/app/generated-videos \
  gemini-image-gen-mcp

🔌 Claude での使用

Claude Desktop の設定

Claude Desktop の設定ファイルに追加します。

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gemini-image-generation": {
      "command": "node",
      "args": ["/full/path/to/gemini-image-gen-mcp/src/mcp-server.js"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key-here"
      }
    }
  }
}

Claude API の使用

# Example prompt to Claude
"Please generate an image of a serene mountain landscape at sunset using the Gemini image generation tool"

Claude は MCP サーバーの generate_image ツールを自動的に呼び出します。

🎨 Web インターフェース

Web インターフェースには、主に 3 つのセクションがあります。

1. Generator タブ

• 画像や動画を生成するためのテキストプロンプトを入力します
• 生成パラメーター（temperature、topP、topK）を調整します
• テストをすばやく行うには、サンプルプロンプトを使用します
• 強化されたプロンプトとともに生成結果を表示します

2. Gallery タブ

• 生成されたすべての画像と動画を閲覧します
• ページネーションに対応しています（1 ページあたり 20 件）
• 新しいものから順に並べ替えられます
• クリックすると、フルサイズで表示できます

3. About タブ

• プロジェクト情報
• 機能一覧
• 設定の詳細
• API ドキュメントへのリンク

📊 パフォーマンスと最適化

レスポンスキャッシュ

• 成功した生成結果を自動的にキャッシュします
• TTL は 30 分です（設定可能）
• 同じプロンプトを繰り返し使用する場合の API コストを削減します
• キャッシュキーには、プロンプト、モデル、パラメーターが含まれます
• /api/cache/stats でキャッシュ統計を確認できます

指数バックオフ

• 動画のポーリングを最適化します（2 秒 → 最大 30 秒）
• API 呼び出しを約 60% 削減します
• API のレート制限を防ぎます

非同期 I/O

• ファイル操作をノンブロッキングで実行します
• サーバーの応答性が向上します
• 同時リクエストをより適切に処理できます

ページネーション

• メモリー使用量が一定です
• 数千件のアイテムがあるギャラリーにも対応します
• 変更日時順に並べ替えられます

🛡️ セキュリティ機能

• ✅ 入力検証 - すべてのパラメーターを express-validator で検証します
• ✅ レート制限 - 2 層システム（一般用と生成専用）
• ✅ リクエストサイズ制限 - DoS 防止のため最大 10MB に制限します
• ✅ CORS 設定 - 環境に基づいてオリジンを制御します
• ✅ 任意の認証 - トークンベースの API セキュリティ
• ✅ ハードコードされたシークレットなし - すべての認証情報は環境変数で管理します

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

よくある問題

「GEMINI_API_KEY is not set」エラー：

# Make sure .env file exists and contains:
GEMINI_API_KEY=your_actual_key_here

ポートがすでに使用されています：

# Change port in .env file:
PORT=3080

キャッシュが機能しません：

# Check cache is enabled in .env:
ENABLE_CACHE=true
# View cache stats:
curl http://localhost:3070/api/cache/stats

レート制限を超過しました：

# Increase limits in .env:
RATE_LIMIT_MAX=200
GENERATION_RATE_LIMIT=50

📝 API リクエストの例

画像を生成する

curl -X POST http://localhost:3070/api/generate-image \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A futuristic cityscape at night with neon lights",
    "temperature": 0.8,
    "topP": 0.95,
    "topK": 40
  }'

動画を生成する

curl -X POST http://localhost:3070/api/generate-video \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A bird flying through a forest",
    "temperature": 1.0
  }'

ページネーションを使用して画像を一覧表示する

curl "http://localhost:3070/api/images?page=1&limit=10"

🤝 コントリビューション

コントリビューションを歓迎します。以下の手順に従ってください。

1. リポジトリをフォークします
2. 機能ブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'Add amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. Pull Request を作成します

開発ガイドライン

• コミット前にテストを実行します：npm test
• 既存のコードスタイルに従います
• 新機能のドキュメントを更新します
• 新しい機能のテストを追加します

📄 ライセンス

ISC

🙏 謝辞

• Model Context Protocol を使用して構築
• Google Gemini AI を利用
• 動画生成には Veo 2.0 を使用

📞 サポート

問題や質問がある場合：

• GitHub で issue を作成してください
• API ドキュメントを確認してください
• 上記のトラブルシューティングのセクションを確認してください

---

AI コミュニティのために ❤️ を込めて作成