ollama-vision-mcp

English · 中文

Минимальный мостовой сервис, который предоставляет локальные vision-возможности для VS Code Copilot, использующего текстовые модели (например, DeepSeek).

Когда Copilot использует текстовую модель, он не может напрямую «видеть» изображения. Этот MCP-сервер устраняет этот пробел: вы кладёте скриншот в папку; Copilot читает изображение через этот мост → отправляет его в локальную Ollama vision-модель → получает обратно текстовое описание, которое текстовая модель может понять.

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

• Хотя бы одна vision-модель загружена; рекомендуется:

  bash

  ollama pull qwen2.5vl:7b

  Другие варианты: qwen3-vl:8b, gemma3:12b, llama3.2-vision:11b, llava:7b. Выберите модель, подходящую для вашего GPU; укажите её позже через переменную окружения VISION_MCP_MODEL.

🚀 Быстрая установка (рекомендуется)

Выполните одну команду в корне репозитория, чтобы завершить установку и настройку:

bash GXP3

Скрипт автоматически:

1. Создаст выделенное виртуальное окружение (.venv) и установит этот пакет (не затрагивая глобальное окружение).

2. Обнаружит локальный сервис Ollama и выведет список доступных vision-моделей.

3. Интерактивно проведёт вас по настройке base_url, model, inbox, max_tokens, сжатия изображений и необязательного API Key.

4. Запишет конфигурацию в .vscode/mcp.json проекта и/или в глобальный MCP-файл уровня пользователя (%APPDATA%\Code\User\mcp.json), объединяя с существующими настройками и не перезаписывая ваши другие MCP-серверы.

Неинтерактивное использование (подходит для CI/скриптов):

bash GXP4

После установки перезагрузите окно в VS Code (Ctrl+Shift+P → «Developer: Reload Window»), чтобы конфигурация вступила в силу.

Если вы уже запускали его ранее, вы также можете перенастроить всё, просто выполнив команду ollama-vision-setup.

Проверка установки

В VS Code Copilot Chat (в режиме агента) введите:

text GXP5

Если возвращённый JSON содержит "ollama": { "ok": true, ... } и список моделей, соединение успешно. Если ok имеет значение false, сначала запустите Ollama (ollama serve) и попробуйте снова.

Использование

1. Поместите скриншоты в каталог inbox проекта (по умолчанию .ai/inbox). Сервер создаст этот каталог автоматически при необходимости.

2. Задайте вопрос в Copilot Chat, например:

   «Посмотри на скриншоты в inbox и скажи, о чём эта ошибка».

3. Агент автоматически вызовет list_images → describe_image и ответит на основе текстового описания.

Сделайте агента умнее (необязательно): скопируйте готовый файл инструкций .github/instructions/ollama-vision/vision-tools.instructions.md в тот же путь в вашем проекте. Он обучает агента полному рабочему процессу vision — порядку вызовов (list_images → describe_image → extract_text), выбору режима, устранению неполадок и подсказывает, куда класть скриншоты (в inbox). Будучи файловой инструкцией VS Code, он обнаруживается по запросу всякий раз, когда задача связана с изображениями, поэтому работает сразу без настройки.

Справочник переменных окружения

Псевдонимы совместимости: VISION_MODEL, VISION_BASE_URL, VISION_INBOX, VISION_API_KEY.

Установка вручную (альтернативный вариант)

Если вам нужен полный ручной контроль над каждым шагом, следуйте приведённому ниже процессу.

1. Создайте окружение и установите

bash GXP6

После установки у вас появятся две команды:

• ollama-vision-mcp — запуск MCP-сервера

• ollama-vision-setup — интерактивный ярлык настройки

2. Зарегистрируйте в VS Code

Скопируйте следующее в .vscode/mcp.json вашего проекта (только для проекта) или в пользовательский файл %APPDATA%\Code\User\mcp.json (для всех проектов). Обязательно измените command на абсолютный путь к интерпретатору Python в вашем виртуальном окружении:

json GXP7

⚠️ command должен быть абсолютным путём к интерпретатору Python внутри виртуального окружения. Вы также можете выполнить ollama-vision-setup --project, чтобы сгенерировать этот файл автоматически. При вызове сервер использует os.getcwd(), поэтому относительные пути (например, path и каталог inbox) будут разрешаться относительно корня проекта, в котором запущен сервер.

Дымовой тест

Выполните следующий скрипт, чтобы проверить подключение к Ollama, вывести содержимое inbox и выполнить реальный vision-вызов на первом изображении:

bash GXP8

Лицензия

MIT