MCP OpenVision

MCP OpenVision

概要

MCP OpenVision は、OpenRouter のビジョンモデルを活用した画像分析機能を提供する Model Context Protocol（MCP）サーバーです。MCP エコシステム内のシンプルなインターフェースを通じて、AI アシスタントが画像を分析できるようにします。

インストール

Smithery 経由でインストールする

Smithery 経由で、Claude Desktop に mcp-openvision を自動的にインストールするには：

npx -y @smithery/cli install @Nazruden/mcp-openvision --client claude

pip を使用する

pip install mcp-openvision

UV を使用する（推奨）

uv pip install mcp-openvision

設定

MCP OpenVision の利用には OpenRouter API キーが必要です。環境変数を使用して設定できます。

• OPENROUTER_API_KEY（必須）：OpenRouter API キー
• OPENROUTER_DEFAULT_MODEL（任意）：使用するビジョンモデル

OpenRouter のビジョンモデル

MCP OpenVision は、ビジョン機能に対応した OpenRouter のあらゆるモデルで動作します。デフォルトのモデルは qwen/qwen2.5-vl-32b-instruct:free ですが、ほかの互換モデルも指定できます。

OpenRouter で利用できる人気のビジョンモデルには、次のものがあります。

• qwen/qwen2.5-vl-32b-instruct:free（デフォルト）
• anthropic/claude-3-5-sonnet
• anthropic/claude-3-opus
• anthropic/claude-3-sonnet
• openai/gpt-4o

OPENROUTER_DEFAULT_MODEL 環境変数を設定するか、image_analysis 関数に model パラメーターを直接渡すことで、カスタムモデルを指定できます。

使用方法

MCP Inspector でテストする

MCP OpenVision をテストする最も簡単な方法は、MCP Inspector ツールを使用することです。

npx @modelcontextprotocol/inspector uvx mcp-openvision

Claude Desktop または Cursor と連携する

1. MCP 設定ファイルを編集します。

   • Windows：%USERPROFILE%\.cursor\mcp.json
   • macOS：~/.cursor/mcp.json または ~/Library/Application Support/Claude/claude_desktop_config.json

2. 次の設定を追加します。

{
  "mcpServers": {
    "openvision": {
      "command": "uvx",
      "args": ["mcp-openvision"],
      "env": {
        "OPENROUTER_API_KEY": "your_openrouter_api_key_here",
        "OPENROUTER_DEFAULT_MODEL": "anthropic/claude-3-sonnet"
      }
    }
  }
}

開発用にローカルで実行する

# Set the required API key
export OPENROUTER_API_KEY="your_api_key"

# Run the server module directly
python -m mcp_openvision

機能

MCP OpenVision は、次のコアツールを提供します。

• image_analysis：ビジョンモデルを使って画像を分析します。さまざまなパラメーターに対応しています。
  • image：次の形式で指定できます。
    • Base64 エンコードされた画像データ
    • 画像 URL（http/https）
    • ローカルファイルパス
  • query：画像分析タスクに対するユーザーの指示
  • system_prompt：モデルの役割と動作を定義する指示（任意）
  • model：使用するビジョンモデル
  • temperature：ランダム性を制御します（0.0～1.0）
  • max_tokens：応答の最大長

効果的なクエリを作成する

query パラメーターは、画像分析から有用な結果を得るうえで重要です。適切に作成されたクエリには、次の情報が含まれます。

1. 目的：この画像を分析する理由
2. 注目点：注意を向けるべき具体的な要素や詳細
3. 必要な情報：抽出する必要がある情報の種類
4. 形式の希望：結果をどのような形式にするか

効果的なクエリの例

基本的なクエリ	改善されたクエリ
"この画像を説明してください"	"この店舗の棚の画像に写っている小売商品をすべて特定し、価格帯を推定してください"
"この画像には何が写っていますか？"	"この医療画像を分析して異常がないか確認し、強調表示された領域に注目して考えられる診断を提示してください"
"このグラフを分析してください"	"四半期ごとの売上を示すこの棒グラフから数値データを抽出し、2022-2023年の主な傾向を特定してください"
"テキストを読んでください"	"このレストランのメニューに見えるテキストをすべて書き起こし、項目名、説明、価格をそのまま保持してください"

分析が必要な理由や、具体的にどのような情報を求めているかを伝えることで、モデルが関連する詳細に焦点を合わせ、より有益な分析結果を提示できるようになります。

使用例

# Analyze an image from a URL
result = await image_analysis(
    image="https://example.com/image.jpg",
    query="Describe this image in detail"
)

# Analyze an image from a local file with a focused query
result = await image_analysis(
    image="path/to/local/image.jpg",
    query="Identify all traffic signs in this street scene and explain their meanings for a driver education course"
)

# Analyze with a base64-encoded image and a specific analytical purpose
result = await image_analysis(
    image="SGVsbG8gV29ybGQ=...",  # base64 data
    query="Examine this product packaging design and highlight elements that could be improved for better visibility and brand recognition"
)

# Customize the system prompt for specialized analysis
result = await image_analysis(
    image="path/to/local/image.jpg",
    query="Analyze the composition and artistic techniques used in this painting, focusing on how they create emotional impact",
    system_prompt="You are an expert art historian with deep knowledge of painting techniques and art movements. Focus on formal analysis of composition, color, brushwork, and stylistic elements."
)

画像入力の種類

image_analysis ツールでは、次の種類の画像入力を使用できます。

1. Base64 エンコードされた文字列
2. 画像 URL - http:// または https:// で始まる必要があります
3. ファイルパス：
   • 絶対パス：/（Unix）またはドライブ文字（Windows）で始まる完全なパス
   • 相対パス：現在の作業ディレクトリを基準とするパス
   • project_root を指定した相対パス：project_root パラメーターを使用して基準ディレクトリを指定します

相対パスの使用

相対ファイルパス（"examples/image.jpg" など）を使用する場合、次の2つの方法があります。

1. パスを、サーバーの実行中の現在の作業ディレクトリからの相対パスにする
2. または、project_root パラメーターを指定する：

# Example with relative path and project_root
result = await image_analysis(
    image="examples/image.jpg",
    project_root="/path/to/your/project",
    query="What is in this image?"
)

これは、現在の作業ディレクトリが予測できないアプリケーションや、特定のディレクトリを基準とするパスでファイルを参照したい場合に特に便利です。

開発

開発環境のセットアップ

# Clone the repository
git clone https://github.com/modelcontextprotocol/mcp-openvision.git
cd mcp-openvision

# Install development dependencies
pip install -e ".[dev]"

コードのフォーマット

このプロジェクトでは、コードの自動フォーマットに Black を使用しています。フォーマットは GitHub Actions によって適用されます。

• リポジトリにプッシュされたすべてのコードは、Black によって自動的にフォーマットされます
• リポジトリのコラボレーターからのプルリクエストでは、Black がコードをフォーマットし、プルリクエストのブランチに直接コミットします
• フォークからのプルリクエストでは、Black がフォーマット済みのコードを含む新しいプルリクエストを作成します。このプルリクエストは元のプルリクエストにマージできます

コミット前に、ローカルで Black を実行してコードをフォーマットすることもできます。

# Format all Python code in the src and tests directories
black src tests

テストの実行

pytest

リリースプロセス

このプロジェクトでは、自動化されたリリースプロセスを使用しています。

1. セマンティック バージョニングの原則に従って、pyproject.toml のバージョンを更新します
   • 補助スクリプトを使用できます：python scripts/bump_version.py [major|minor|patch]
2. 新しいバージョンの詳細を CHANGELOG.md に追加します
   • このスクリプトは CHANGELOG.md に記入用のテンプレートエントリーも作成します
3. これらの変更を main ブランチにコミットしてプッシュします
4. GitHub Actions のワークフローが次の処理を行います。
   • バージョンの変更を検出する
   • 新しい GitHub リリースを自動的に作成する
   • PyPI に公開するパブリッシングワークフローを開始する

この自動化により、一貫したリリースプロセスを維持し、すべてのリリースで適切なバージョン管理とドキュメント化を実現できます。

サポート

このプロジェクトが役に立った場合は、コーヒーをごちそうして、継続的な開発とメンテナンスを支援することをご検討ください。

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細は LICENSE ファイルをご覧ください。