MCP Image Validator

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

Related MCP server: readpic MCP Server

Что это?

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 (получить здесь)

Установка

# Клонируйте репозиторий
git clone <url-репозитория>
cd mcp-image-validator

# Установите зависимости
pip install -r requirements.txt

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

# Скопируйте шаблон
cp .env.example .env

# Отредактируйте .env и добавьте ваш API ключ
# Получить ключ: https://ollama.com/settings/keys

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

OLLAMA_API_KEY=ваш_api_ключ_здесь
VISION_MODEL=qwen3-vl:235b-cloud
OLLAMA_BASE_URL=https://ollama.com/v1
VISION_TEMPERATURE=0.2
VISION_MAX_TOKENS=1000

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

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

python test_full.py

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

• ✅ Проверку подключения к 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):

{
  "mcpServers": {
    "image-validator": {
      "command": "python",
      "args": ["c:\\GIT\\mcp-image-validator\\server.py"],
      "env": {
        "OLLAMA_API_KEY": "ваш_api_ключ_здесь"
      }
    }
  }
}

Важно:

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

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

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

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

Опиши изображение по пути C:\Users\user\Pictures\photo.jpg

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

describe_image

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

Параметры:

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

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

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

Опиши изображение по пути C:\Photos\landscape.jpg

Проанализируй изображение C:\Docs\diagram.png и перечисли все компоненты

Что изображено на фото /home/user/pictures/sunset.jpg?

Поддерживаемые форматы: 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

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

Claude Code → MCP Protocol → server.py → ollama_vision_client.py
                                              ↓
                                         OpenAI SDK
                                              ↓
                                    Ollama Cloud API
                                              ↓
                                       Qwen3-VL Model

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

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

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

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

mcp-image-validator/
├── server.py                   # MCP сервер (stdio transport)
├── ollama_vision_client.py     # Клиент Ollama Cloud API
├── test_full.py                # Полный функциональный тест
├── requirements.txt            # Python зависимости
├── .env.example                # Шаблон переменных окружения
├── .gitignore                  # Правила для git
└── README.md                   # Этот файл

Разработка

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

python server.py

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

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

# Полный функциональный тест
python test_full.py

# С конкретным изображением
python test_full.py
# Введите путь к изображению когда будет предложено

Логирование

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

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

logging.basicConfig(level=logging.DEBUG)

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

"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 ключ действителен и имеет активные кредиты

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

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

Опиши изображение по пути C:\Users\user\Pictures\photo.jpg

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

Проанализируй изображение C:\Docs\screenshot.png и перечисли все видимые элементы интерфейса

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

Для изображения /home/user/vacation.jpg:
1. Опиши главный объект
2. Какие цвета преобладают?
3. Какая атмосфера или настроение?

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 - Валидация и обработка изображений

Установка:

pip install -r requirements.txt

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

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

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

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

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

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

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

@mcp.tool()
def analyze_colors(image_path: str) -> dict:
    """Анализирует цветовую палитру изображения"""
    # Ваша реализация
    pass

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

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

# Другие vision модели с суффиксом -cloud
VISION_MODEL=llava:7b-cloud
VISION_MODEL=bakllava:7b-cloud

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

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

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

• 🔍 Дополнительные инструменты анализа (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)

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

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