Ai Vision MCP

🚀 AI Vision MCP Server

強力なModel Context Protocol (MCP)サーバーです。Google GeminiとVertex AIモデルを使用して、AIによる画像およびビデオ分析を提供します。

🚀 クイックスタート

前提条件

googleプロバイダーまたはvertex_aiプロバイダーのいずれかを選択できます。簡単に始めるには、googleプロバイダーをおすすめします。

選択したプロバイダーに基づいて設定する必要がある環境変数を以下に示します。（注: MCPクライアントのタイムアウト設定を5分以上に設定することをおすすめします。）

(i) Google AI Studioプロバイダーを使用する場合

export IMAGE_PROVIDER="google" # or vertex_ai
export VIDEO_PROVIDER="google" # or vertex_ai
export GEMINI_API_KEY="your-gemini-api-key"

Google AI StudioのAPIキーはこちらから取得できます。

(ii) Vertex AIプロバイダーを使用する場合

export IMAGE_PROVIDER="vertex_ai"
export VIDEO_PROVIDER="vertex_ai"
export VERTEX_CREDENTIALS="/path/to/service-account.json"
export GCS_BUCKET_NAME="your-gcs-bucket"

設定方法については、こちらのガイドを参照してください。

インストール

以下は、Claude Desktop、Claude Code、Cursor、Clineなど、さまざまなMCPクライアントでこのMCPをインストールするガイドです。

{
  "mcpServers": {
    "ai-vision-mcp": {
      "command": "npx",
      "args": ["ai-vision-mcp"],
      "env": {
        "IMAGE_PROVIDER": "google",
        "VIDEO_PROVIDER": "google",
        "GEMINI_API_KEY": "your-gemini-api-key"
      }
    }
  }
}

{
  "mcpServers": {
    "ai-vision-mcp": {
      "command": "npx",
      "args": ["ai-vision-mcp"],
      "env": {
        "IMAGE_PROVIDER": "vertex_ai",
        "VIDEO_PROVIDER": "vertex_ai",
        "VERTEX_CREDENTIALS": "/path/to/service-account.json",
        "GCS_BUCKET_NAME": "ai-vision-mcp-{VERTEX_PROJECT_ID}"
      }
    }
  }
}

claude mcp add ai-vision-mcp \
  -e IMAGE_PROVIDER=google \
  -e VIDEO_PROVIDER=google \
  -e GEMINI_API_KEY=your-gemini-api-key \
  -- npx ai-vision-mcp

claude mcp add ai-vision-mcp \
  -e IMAGE_PROVIDER=vertex_ai \
  -e VIDEO_PROVIDER=vertex_ai \
  -e VERTEX_CREDENTIALS=/path/to/service-account.json \
  -e GCS_BUCKET_NAME=ai-vision-mcp-{VERTEX_PROJECT_ID} \
  -- npx ai-vision-mcp

{
  "env": {
    "MCP_TIMEOUT": "60000",
    "MCP_TOOL_TIMEOUT": "300000"
  }
}

{
  "mcpServers": {
    "ai-vision-mcp": {
      "command": "npx",
      "args": ["ai-vision-mcp"],
      "env": {
        "IMAGE_PROVIDER": "google",
        "VIDEO_PROVIDER": "google",
        "GEMINI_API_KEY": "your-gemini-api-key"
      }
    }
  }
}

{
  "mcpServers": {
    "ai-vision-mcp": {
      "command": "npx",
      "args": ["ai-vision-mcp"],
      "env": {
        "IMAGE_PROVIDER": "vertex_ai",
        "VIDEO_PROVIDER": "vertex_ai",
        "VERTEX_CREDENTIALS": "/path/to/service-account.json",
        "GCS_BUCKET_NAME": "ai-vision-mcp-{VERTEX_PROJECT_ID}"
      }
    }
  }
}

{
  "mcpServers": {
    "timeout": 300, 
    "type": "stdio",
    "ai-vision-mcp": {
      "command": "npx",
      "args": ["ai-vision-mcp"],
      "env": {
        "IMAGE_PROVIDER": "google",
        "VIDEO_PROVIDER": "google",
        "GEMINI_API_KEY": "your-gemini-api-key"
      }
    }
  }
}

{
  "mcpServers": {
    "ai-vision-mcp": {
      "timeout": 300,
      "type": "stdio",
      "command": "npx",
      "args": ["ai-vision-mcp"],
      "env": {
        "IMAGE_PROVIDER": "vertex_ai",
        "VIDEO_PROVIDER": "vertex_ai",
        "VERTEX_CREDENTIALS": "/path/to/service-account.json",
        "GCS_BUCKET_NAME": "ai-vision-mcp-{VERTEX_PROJECT_ID}"
      }
    }
  }
}

npx ai-vision-mcp

✨ 主な機能

• 2つのプロバイダーサポート: Google Gemini APIとVertex AIのどちらかを選択できます。
• マルチモーダル分析: 画像とビデオの両方のコンテンツ分析をサポートします。
• 柔軟なファイル処理: 複数の方法（URL、ローカルファイル、base64）でのアップロードをサポートします。
• ストレージ統合: 組み込みのGoogle Cloud Storageサポートがあります。
• 包括的な検証: Zodベースのデータ検証が全体に適用されます。
• エラーハンドリング: リトライロジックとサーキットブレーカーを備えた堅牢なエラーハンドリングがあります。
• TypeScript: 厳密な型チェックを備えた完全なTypeScriptサポートがあります。

💻 使用例

基本的な使用法

このサーバーは4つの主要なMCPツールを提供します。

1) analyze_image

AIを使用して画像を分析し、詳細な説明を返します。

パラメーター:

• imageSource (string): 画像のURL、base64データ、またはファイルパス
• prompt (string): AIに対する質問または指示
• options (object, optional): 分析オプション（温度と最大トークン数を含む）

例:

1. URLから画像を分析する場合

{
  "imageSource": "https://plus.unsplash.com/premium_photo-1710965560034-778eedc929ff",
  "prompt": "What is this image about? Describe what you see in detail."
}

2. ローカル画像ファイルを分析する場合

{
  "imageSource": "C:\\Users\\username\\Downloads\\image.jpg",
  "prompt": "What is this image about? Describe what you see in detail."
}

2) compare_images

AIを使用して複数の画像を比較し、詳細な比較分析を返します。

パラメーター:

• imageSources (array): 画像ソースの配列（URL、base64データ、またはファイルパス） - 最小2つ、最大4つの画像
• prompt (string): 画像を比較するための質問または指示
• options (object, optional): 分析オプション（温度と最大トークン数を含む）

例:

1. URLから画像を比較する場合

{
  "imageSources": [
    "https://example.com/image1.jpg",
    "https://example.com/image2.jpg"
  ],
  "prompt": "Compare these two images and tell me the differences"
}

2. 混合ソースを比較する場合

{
  "imageSources": [
    "https://example.com/image1.jpg",
    "C:\\\\Users\\\\username\\\\Downloads\\\\image2.jpg",
    "data:image/jpeg;base64,/9j/4AAQSkZJRgAB..."
  ],
  "prompt": "Which image has the best lighting quality?"
}

3) detect_objects_in_image

AIビジョンモデルを使用して画像内のオブジェクトを検出し、バウンディングボックス付きの注釈付き画像を生成します。検出されたオブジェクトと座標を返し、注釈付き画像をファイルまたは一時ディレクトリに保存します。

パラメーター:

• imageSource (string): 画像のURL、base64データ、またはファイルパス
• prompt (string): 画像内で検出または認識するものを説明するカスタム検出プロンプト
• outputFilePath (string, optional): 注釈付き画像の明示的な出力パス

設定: この関数はオブジェクト検出に最適化されたデフォルトパラメーターを使用し、ランタイムのoptionsパラメーターを受け付けません。AIパラメーター（温度、topP、topK、maxTokens）をカスタマイズするには、環境変数を使用してください。

# Recommended environment variable settings for object detection (these are now the defaults)
TEMPERATURE_FOR_DETECT_OBJECTS_IN_IMAGE=0.0     # Deterministic responses
TOP_P_FOR_DETECT_OBJECTS_IN_IMAGE=0.95          # Nucleus sampling
TOP_K_FOR_DETECT_OBJECTS_IN_IMAGE=30            # Vocabulary selection
MAX_TOKENS_FOR_DETECT_OBJECTS_IN_IMAGE=8192     # High token limit for JSON

ファイル処理ロジック:

1. 明示的なoutputFilePathが指定された場合 → 指定された正確なパスに保存します。
2. 明示的なoutputFilePathが指定されない場合 → 自動的に一時ディレクトリに保存します。

レスポンスタイプ:

• 明示的なoutputFilePathが指定された場合、fileオブジェクトを返します。
• 明示的なoutputFilePathが指定されない場合、tempFileオブジェクトを返し、画像ファイル出力は自動的に一時フォルダに保存されます。
• 常に検出されたオブジェクトと座標を含むdetections配列を含みます。
• ブラウザ自動化用のパーセンテージベースの座標を含むsummaryを含みます。

例:

1. 基本的なオブジェクト検出

{
  "imageSource": "https://example.com/image.jpg",
  "prompt": "Detect all objects in this image"
}

2. 注釈付き画像を特定のパスに保存する場合

{
  "imageSource": "C:\\Users\\username\\Downloads\\image.jpg",
  "outputFilePath": "C:\\Users\\username\\Documents\\annotated_image.png"
}

3. カスタム検出プロンプト

{
  "imageSource": "data:image/jpeg;base64,/9j/4AAQSkZJRgAB...",
  "prompt": "Detect and label all electronic devices in this image"
}

4) analyze_video

AIを使用してビデオを分析し、詳細な説明を返します。

パラメーター:

• videoSource (string): YouTube URL、GCS URI、またはビデオのローカルファイルパス
• prompt (string): AIに対する質問または指示
• options (object, optional): 分析オプション（温度と最大トークン数を含む）

サポートされるビデオソース:

• YouTube URLs (e.g., https://www.youtube.com/watch?v=...)
• ローカルファイルパス (e.g., C:\Users\username\Downloads\video.mp4)

例:

1. YouTube URLからビデオを分析する場合

{
  "videoSource": "https://www.youtube.com/watch?v=9hE5-98ZeCg",
  "prompt": "What is this video about? Describe what you see in detail."
}

2. ローカルビデオファイルを分析する場合

{
  "videoSource": "C:\\Users\\username\\Downloads\\video.mp4",
  "prompt": "What is this video about? Describe what you see in detail."
}

注: パブリックビデオURLとしてはYouTube URLのみがサポートされています。他のパブリックビデオURLは現在サポートされていません。

📚 ドキュメント

環境構成

基本的なセットアップでは、プロバイダーの選択と必要な資格情報の構成のみが必要です。

Google AI Studioプロバイダー（推奨）

export IMAGE_PROVIDER="google"
export VIDEO_PROVIDER="google"
export GEMINI_API_KEY="your-gemini-api-key"

Vertex AIプロバイダー（本番環境）

export IMAGE_PROVIDER="vertex_ai"
export VIDEO_PROVIDER="vertex_ai"
export VERTEX_CREDENTIALS="/path/to/service-account.json"
export GCS_BUCKET_NAME="your-gcs-bucket"

📖 詳細な構成ガイド

包括的な環境変数のドキュメントには、以下が含まれます。

• 完全な構成リファレンス（60以上の環境変数）
• 関数固有の最適化例
• 高度な構成パターン
• トラブルシューティングガイダンス

👉 環境変数ガイドを参照

構成の優先順位の概要

このサーバーは階層的な構成システムを使用しており、より具体的な設定が一般的な設定を上書きします。

1. LLMによって割り当てられた値（ツール呼び出しのランタイムパラメーター）
2. 関数固有の変数 (TEMPERATURE_FOR_ANALYZE_IMAGEなど)
3. タスク固有の変数 (TEMPERATURE_FOR_IMAGEなど)
4. 汎用変数 (TEMPERATUREなど)
5. システムデフォルト

# General settings
export TEMPERATURE=0.7
export MAX_TOKENS=1500

# Task-specific optimization
export TEMPERATURE_FOR_IMAGE=0.2     # More precise for images
export TEMPERATURE_FOR_VIDEO=0.5     # More creative for videos

# Optimize individual functions
export TEMPERATURE_FOR_ANALYZE_IMAGE=0.1
export TEMPERATURE_FOR_COMPARE_IMAGES=0.3
export TEMPERATURE_FOR_DETECT_OBJECTS_IN_IMAGE=0.0  # Deterministic
export MAX_TOKENS_FOR_DETECT_OBJECTS_IN_IMAGE=8192   # High token limit

# Choose models per function
export ANALYZE_IMAGE_MODEL="gemini-2.5-flash-lite"
export COMPARE_IMAGES_MODEL="gemini-2.5-flash"
export ANALYZE_VIDEO_MODEL="gemini-2.5-flash-pro"

開発

前提条件

• Node.js 18+
• npmまたはyarn

セットアップ

# Clone the repository
git clone https://github.com/tan-yong-sheng/ai-vision-mcp.git
cd ai-vision-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Start development server
npm run dev

スクリプト

• npm run build - TypeScriptプロジェクトをビルドします。
• npm run dev - ウォッチモードで開発サーバーを起動します。
• npm run lint - ESLintを実行します。
• npm run format - Prettierでコードをフォーマットします。
• npm start - ビルドされたサーバーを起動します。

アーキテクチャ

このプロジェクトはモジュール型のアーキテクチャに従っています。

src/
├── providers/          # AI provider implementations
│   ├── gemini/        # Google Gemini provider
│   ├── vertexai/      # Vertex AI provider
│   └── factory/       # Provider factory
├── services/          # Core services
│   ├── ConfigService.ts
│   └── FileService.ts
├── storage/           # Storage implementations
├── file-upload/       # File upload strategies
├── types/            # TypeScript type definitions
├── utils/            # Utility functions
└── server.ts         # Main MCP server

エラーハンドリング

このサーバーには包括的なエラーハンドリングが含まれています。

• 検証エラー: Zodスキーマを使用した入力検証
• ネットワークエラー: 指数バックオフを伴う自動リトライ
• 認証エラー: APIキーの問題に対する明確なエラーメッセージ
• ファイルエラー: ファイルサイズ制限と形式制限のハンドリング

🔧 技術詳細

このプロジェクトは、Google GeminiとVertex AIを使用して画像およびビデオ分析を行う強力なModel Context Protocol (MCP)サーバーです。モジュール型のアーキテクチャを採用しており、各機能は独立したモジュールとして実装されています。また、Zodを使用したデータ検証、指数バックオフを伴う自動リトライ、サーキットブレーカーを備えた堅牢なエラーハンドリングが実装されています。

📄 ライセンス

このプロジェクトはMITライセンスのもとで公開されています。詳細についてはLICENSEファイルを参照してください。

謝辞

• GoogleのGeminiとVertex AI API
• Model Context ProtocolチームのMCPフレームワーク
• このプロジェクトのすべての貢献者とユーザー