Skip to main content
Glama

MCP Image Validator

by AronMav
GitHub
Python
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

MCP Image Validator

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

Python 3.10+ License: MIT MCP

Что это?

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 для лёгкой настройки

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

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

Требования

Установка

# Клонируйте репозиторий 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

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

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

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)

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

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

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Enables Claude and other MCP clients to analyze and describe images using the Qwen3-VL vision model (235B parameters) through Ollama Cloud API, supporting multiple image formats without requiring local GPU.

  1. Python 3.10+ License: MIT MCP
    1. Что это?
      1. Быстрый старт
        1. Требования
        2. Установка
        3. Конфигурация
        4. Проверка работы
        5. Использование с Claude Code
      2. Доступный инструмент
        1. describe_image
      3. Переменные окружения
        1. Архитектура
          1. Структура проекта
            1. Разработка
              1. Запуск сервера напрямую
              2. Тестирование
              3. Логирование
            2. Устранение неполадок
              1. "OLLAMA_API_KEY not set"
              2. "Image file not found"
              3. "Unsupported image format"
              4. Медленные ответы (10-30+ секунд)
              5. Сервер не загружается в Claude Code
              6. "Connection refused" или "Network error"
            3. Примеры использования
              1. Базовое описание
              2. С кастомным промптом
              3. Множественные аспекты
            4. Технические характеристики
              1. Требования
              2. Зависимости
              3. Производительность
            5. Расширение функциональности
              1. Добавление новых инструментов
              2. Использование других моделей
            6. Вклад в проект
              1. Документация
                1. Лицензия
                  1. Ссылки
                    1. Поддержка

                      New MCP Servers

                      MCP directory API

                      We provide all the information about MCP servers via our MCP API.

                      curl -X GET 'https://glama.ai/api/mcp/v1/servers/AronMav/mcp-image-validator'

                      If you have feedback or need assistance with the MCP directory API, please join our Discord server