MCP Image Validator

Python MCP (Model Context Protocol) сервер для описания изображений с использованием модели Qwen3-VL через Ollama Cloud.

Что это?

MCP сервер, который позволяет Claude Code и другим MCP клиентам анализировать изображения с помощью облачной vision модели Qwen3-VL (235B параметров) от Ollama Cloud.

Основные возможности:

• 🖼️ Анализ изображений - Детальное описание с помощью Qwen3-VL (235B параметров)

• ☁️ Облачные вычисления - Работает через Ollama Cloud API (не требует GPU)

• 🔌 MCP совместимость - Готов к использованию в Claude Code

• 🎨 Поддержка форматов - JPEG, PNG, GIF, WebP, BMP

• 🛠️ Простота - Построен на FastMCP для лёгкой настройки

• ⚡ Проверено - Протестировано и готово к работе

Быстрый старт

Требования

• Python 3.10 или выше

• API ключ Ollama Cloud (получить здесь)

Установка

Конфигурация

Содержимое .env:

Проверка работы

После настройки .env проверьте работу сервиса:

Скрипт выполнит:

• ✅ Проверку подключения к Ollama Cloud

• ✅ Поиск тестового изображения в директории (test.jpg, test.png, sample.jpg, sample.png)

• ✅ Анализ изображения с помощью Qwen3-VL

• ✅ Вывод детального описания

Если тестовое изображение не найдено, скрипт предложит ввести путь к вашему изображению.

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

Добавьте в настройки MCP Claude Code (.claude/mcp_settings.json или claude_desktop_config.json):

Важно:

• Используйте абсолютные пути

• Укажите API ключ в секции env

• Перезапустите Claude Code после добавления конфигурации

Затем в диалоге с Claude Code:

Доступный инструмент

describe_image

Анализирует изображение и предоставляет детальное описание с использованием Qwen3-VL.

Параметры:

• image_path (строка, обязательно) - Абсолютный путь к файлу изображения

• prompt (строка, опционально) - Пользовательский промпт для модели

Примеры использования:

Поддерживаемые форматы: JPEG, PNG, GIF, WebP, BMP

Переменные окружения

Примечание: Модели Ollama Cloud должны иметь суффикс -cloud (например, qwen3-vl:235b-cloud).

Архитектура

Сервер использует FastMCP (фреймворк от Anthropic) и OpenAI SDK, настроенный для работы с Ollama Cloud.

Компоненты:

• MCP Server (server.py) - FastMCP сервер с stdio транспортом

• Ollama Client (ollama_vision_client.py) - Клиент API для обработки изображений

• Qwen3-VL Model - Vision модель на 235B параметров на Ollama Cloud

Поток данных:

Основано на проверенных паттернах:

• comfyui-mcp-server - архитектура MCP сервера

• doc-chatbot - интеграция с Ollama Cloud

Структура проекта

Разработка

Запуск сервера напрямую

Сервер запустится и будет ожидать MCP протокольные сообщения на stdin.

Тестирование

Логирование

Логи сервера выводятся в stderr. При запуске через Claude Code логи доступны в панели MCP серверов.

Для более детального логирования измените в server.py:

Устранение неполадок

"OLLAMA_API_KEY not set"

Решение:

• Убедитесь, что файл .env существует с корректным ключом

• При использовании с Claude Code укажите ключ в env секции настроек MCP

"Image file not found"

Решение:

• Используйте только абсолютные пути к изображениям

• Проверьте существование файла: dir "C:\path\to\image.jpg" (Windows) или ls -la /path/to/image.jpg (Linux/Mac)

"Unsupported image format"

Решение:

• Поддерживаются только: JPEG, PNG, GIF, WebP, BMP

• Проверьте, что расширение файла соответствует реальному формату

Медленные ответы (10-30+ секунд)

Это нормально!

• Vision модели с 235B параметров требуют времени на обработку

• Облачные модели имеют сетевую задержку

• Для более быстрой работы можно попробовать модели меньшего размера

Сервер не загружается в Claude Code

Проверьте:

• Путь в настройках MCP абсолютный и корректный

• Используется команда python (или python3 на некоторых системах)

• Claude Code перезапущен после изменения конфигурации

• Логи MCP сервера на наличие ошибок

"Connection refused" или "Network error"

Проверьте:

• Интернет соединение активно

• Доступ к ollama.com не заблокирован фаерволом

• API ключ действителен и имеет активные кредиты

Примеры использования

Базовое описание

С кастомным промптом

Множественные аспекты

Claude Code автоматически использует инструмент describe_image на основе вашего запроса.

Технические характеристики

Требования

• Python 3.10 или выше

• Интернет соединение (для Ollama Cloud API)

• API ключ Ollama Cloud

Зависимости

• mcp ≥1.0.0 - FastMCP фреймворк

• openai ≥1.0.0 - OpenAI SDK (совместимость с Ollama Cloud)

• python-dotenv ≥1.0.0 - Управление переменными окружения

• Pillow ≥10.0.0 - Валидация и обработка изображений

Установка:

Производительность

• Время ответа: 10-30 секунд (зависит от изображения и загрузки сервера)

• Качество: Высокое (модель 235B параметров)

• Стабильность: Production-ready

Расширение функциональности

Добавление новых инструментов

Пример добавления нового инструмента:

Использование других моделей

Измените VISION_MODEL в .env:

Вклад в проект

Приветствуются любые вклады! Интересные направления:

• 📦 Пакетная обработка изображений

• 🔍 Дополнительные инструменты анализа (OCR, определение объектов)

• 🎨 Поддержка других vision моделей

• 📊 Потоковая передача прогресса

• 🧪 Unit и интеграционные тесты

• 📚 Примеры использования

Создавайте Issues или Pull Requests на GitHub.

Документация

• README.md - Этот файл (основная документация)

• test_full.py - Исходный код теста с примерами

Лицензия

MIT License - См. файл LICENSE для деталей.

Ссылки

• Ollama Cloud - Облачная платформа для AI моделей

• Ollama API Keys - Получить API ключ

• MCP Protocol - Спецификация Model Context Protocol

• Claude Code - AI ассистент для разработки

• FastMCP - Фреймворк для MCP серверов

Поддержка

Для получения помощи:

1. 📖 Проверьте раздел Устранение неполадок

2. 🐛 Создайте Issue на GitHub с:

   • Версией Python (python --version)

   • Сообщениями об ошибках из логов

   • Шагами для воспроизведения проблемы