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

Установка

# Клонируйте репозиторий
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_API_KEY`	-	Обязательно. API ключ от Ollama Cloud
`VISION_MODEL`	`qwen3-vl:235b-cloud`	Vision модель для использования
`OLLAMA_BASE_URL`	`https://ollama.com/v1`	Адрес Ollama Cloud API
`VISION_TEMPERATURE`	`0.2`	Температура генерации (0.0-1.0, меньше = детерминированнее)
`VISION_MAX_TOKENS`	`1000`	Максимальное количество токенов в ответе

Примечание: Модели 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 серверов

Поддержка

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

📖 Проверьте раздел Устранение неполадок
🐛 Создайте Issue на GitHub с:
- Версией Python (python --version)
- Сообщениями об ошибках из логов
- Шагами для воспроизведения проблемы

MCP Image Validator

Python MCP (Model Context Protocol) сервер для описания изображений с использованием модели Qwen3-VL через 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_API_KEY`	-	Обязательно. API ключ от Ollama Cloud
`VISION_MODEL`	`qwen3-vl:235b-cloud`	Vision модель для использования
`OLLAMA_BASE_URL`	`https://ollama.com/v1`	Адрес Ollama Cloud API
`VISION_TEMPERATURE`	`0.2`	Температура генерации (0.0-1.0, меньше = детерминированнее)
`VISION_MAX_TOKENS`	`1000`	Максимальное количество токенов в ответе

Примечание: Модели 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 серверов

Поддержка

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

📖 Проверьте раздел Устранение неполадок
🐛 Создайте Issue на GitHub с:
- Версией Python (python --version)
- Сообщениями об ошибках из логов
- Шагами для воспроизведения проблемы