ollama-vision-mcp

English · 中文

テキストのみのモデル（例: DeepSeek）を使用するVS Code Copilotにローカルビジョン機能を提供する最小限のブリッジサービスです。

Copilotがテキストのみのモデルを使用する場合、画像を直接「見る」ことはできません。このMCPサーバーがそのギャップを埋めます: スクリーンショットをフォルダにドロップすると、Copilotはこのブリッジを介して画像を読み取り、ローカルのOllamaビジョンモデルに送信し、テキストによる説明を受け取ります。これにより、テキストのみのモデルでも理解できるようになります。

VS Code Copilot Chat (Agent mode, text-only model)
        │  MCP stdio
        ▼
ollama-vision-mcp (this package)
        │  Read local image → base64 → POST /v1/chat/completions
        ▼
Ollama (local vision model, e.g., qwen2.5vl:7b)

ツール

Related MCP server: Hybrid Vision MCP Server

このツールの対象範囲

このパッケージはブリッジ層のみです。Ollamaとは純粋にHTTP（OpenAI互換の/v1/chat/completionsおよび/v1/models）で通信します。

以下は処理しません:

• Ollamaのインストール、ollama serveの起動、モデルのプル、モデル設定の管理;

• クリップボードへのアクセス、IDEの内部メカニズム、ローカルのOllama以外のネットワークサービスへのアクセス。

Ollamaのインストールとモデルのプルはすべてお客様の責任で行ってください（前提条件を参照）。

前提条件

以下はご自身でセットアップする必要があります:

• Python 3.10+

• Ollamaがインストールされ、実行されていること: ollama serve

• 少なくとも1つのビジョンモデルがプルされていること。推奨:

  bash

  ollama pull qwen2.5vl:7b

  他のオプション: qwen3-vl:8b, gemma3:12b, llama3.2-vision:11b, llava:7b。 GPUに適したモデルを選択し、後でVISION_MCP_MODEL環境変数で指定してください。

🚀 クイックインストール（推奨）

リポジトリのルートで1つのコマンドを実行するだけで、インストールと設定が完了します:

bash

cd ollama-vision-mcp
python setup_mcp.py

スクリプトは自動的に以下を行います:

1. 専用の仮想環境（.venv）を作成し、このパッケージをインストールします（グローバル環境を汚しません）。

2. ローカルのOllamaサービスを検出し、利用可能なビジョンモデルを一覧表示します。

3. 対話形式でbase_url、model、inbox、max_tokens、画像圧縮、オプションのAPIキーを設定するように案内します。

4. 設定をプロジェクトの.vscode/mcp.jsonおよび/またはユーザーレベルのグローバルMCPファイル（%APPDATA%\Code\User\mcp.json）に書き込みます。既存の設定とマージし、他のMCPサーバーを上書きしません。

非対話型の使用法（CI/スクリプト向け）:

bash

python setup_mcp.py --yes --project --model qwen2.5vl:7b
python setup_mcp.py --print         # Only prints the config JSON, does not write to file

インストール後、VS Codeでウィンドウの再読み込み（Ctrl+Shift+P → 「開発者: ウィンドウの再読み込み」）を行って設定を有効にしてください。

以前に実行したことがある場合は、ollama-vision-setupコマンドを使用するだけで再設定できます。

インストールの確認

VS Code Copilot Chat（エージェントモード）で、次のように入力します:

text

Run vision_status

返されたJSONに"ollama": { "ok": true, ... }とモデルリストが含まれていれば、接続は成功です。 okがfalseの場合は、まずOllama（ollama serve）を起動してから再試行してください。

使用方法

1. スクリーンショットをプロジェクトのインボックスディレクトリ（デフォルトは.ai/inbox）に置きます。必要に応じてサーバーがこのディレクトリを自動的に作成します。

2. Copilot Chatで質問してください。例:

   「インボックスのスクリーンショットを見て、このエラーが何に関するものか教えてください。」

3. エージェントは自動的にlist_images → describe_imageを呼び出し、テキストによる説明に基づいて回答します。

エージェントを賢くする（オプション）: 既製の指示ファイル.github/instructions/ollama-vision/vision-tools.instructions.mdをプロジェクト内の同じパスにコピーします。これにより、エージェントに完全なビジョンワークフロー（呼び出し順序（list_images → describe_image → extract_text）、モード選択、トラブルシューティング、スクリーンショットをインボックスにドロップするように案内する方法）を教えることができます。VS Codeのファイル指示として、画像を扱うタスクのたびにオンデマンドで検出されるため、セットアップ不要ですぐに機能します。

環境変数リファレンス

互換性エイリアス: VISION_MODEL、VISION_BASE_URL、VISION_INBOX、VISION_API_KEY。

手動インストール（代替）

各手順を完全に手動で制御する必要がある場合は、以下のプロセスを参照してください。

1. 環境を作成してインストール

bash

cd ollama-vision-mcp
python -m venv .venv
.venv\Scripts\activate          # Windows
# source .venv/bin/activate    # macOS / Linux
pip install -e .

インストール後、次の2つのコマンドが利用できます:

• ollama-vision-mcp — MCPサーバーを起動

• ollama-vision-setup — 対話型設定のショートカット

2. VS Codeに登録

以下をプロジェクトの.vscode/mcp.json（プロジェクトのみ）またはユーザーレベルのファイル%APPDATA%\Code\User\mcp.json（すべてのプロジェクト）にコピーします。commandを仮想環境のPythonインタープリターの絶対パスに変更してください:

json

{
  "servers": {
    "ollama-vision": {
      "type": "stdio",
      "command": "D:/MyRepos/ollama-vision-mcp/.venv/Scripts/python.exe",
      "args": ["-m", "ollama_vision_mcp"],
      "env": {
        "VISION_MCP_BASE_URL": "http://localhost:11434/v1",
        "VISION_MCP_MODEL": "qwen2.5vl:7b",
        "VISION_MCP_INBOX": ".ai/inbox"
      }
    }
  }
}

⚠️ commandは仮想環境内のPythonインタープリターへの絶対パスである必要があります。 ollama-vision-setup --projectを実行して、このファイルを自動生成することもできます。 サーバーは起動時にos.getcwd()を使用するため、相対パス（pathやインボックスディレクトリなど）はサーバーが起動されたプロジェクトルートを基準に解決されます。

スモークテスト

次のスクリプトを実行して、Ollamaの接続を確認し、インボックスの内容を一覧表示し、最初の画像に対して実際のビジョン呼び出しを行います:

bash

python examples/smoke_test.py

ライセンス

MIT