🪄 ImageSorcery MCP

Магия локального распознавания и редактирования изображений на базе ComputerVision для AI-ассистентов

Official website: imagesorcery.net

✅ С ImageSorcery MCP

🪄 ImageSorcery наделяет AI-ассистентов мощными возможностями обработки изображений:

• ✅ Обрезка, изменение размера и поворот изображений с высокой точностью

• ✅ Удаление фона

• ✅ Рисование текста и форм на изображениях

• ✅ Добавление логотипов и водяных знаков

• ✅ Обнаружение объектов с помощью современных моделей

• ✅ Извлечение текста с изображений с помощью OCR

• ✅ Использование широкого спектра предобученных моделей для обнаружения объектов, OCR и прочего

• ✅ Всё это выполняется локально, без отправки ваших изображений на серверы

Просто попросите ваш AI помочь с задачами по работе с изображениями:

"скопируйте фотографии с животными из папки photos в папку pets"

"Найдите кота на photo.jpg и обрежьте изображение так, чтобы кот оказался по центру по высоте и ширине"

😉 Подсказка: Указывайте полный путь к файлам.**

"Перечислите поля формы на этом form.jpg с помощью модели foduucom/web-form-ui-field-detection и заполните form.md списком описанных полей"

😉 Подсказка: Укажите модель и порог доверия (confidence).

😉 Подсказка: Добавьте "use imagesorcery", чтобы гарантировать использование нужного инструмента.**

Ваш инструмент будет объединять несколько инструментов, перечисленных ниже, чтобы достигнуть цели.

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

Инструмент	Описание	Пример запроса
blur	Размывает указанные прямоугольные или полигональные области изображения с использованием OpenCV. Также можно инвертировать указанные области, например, чтобы размыть фон.	"Blur the area from (150, 100) to (250, 200) with a blur strength of 21 in my image 'test_image.png' and save it as 'output.png'"
change_color	Меняет палитру цвета изображения	"Convert my image 'test_image.png' to sepia and save it as 'output.png'"
config	Просмотр и обновление настроек ImageSorcery MCP	"Show me the current configuration" or "Set the default detection confidence to 0.8"
crop	Обрезает изображение с использованием подхода NumPy в OpenCV	"Crop my image 'input.png' from coordinates (10,10) to (200,200) and save it as 'cropped.png'"
detect	Обнаруживает объекты на изображении с использованием моделей Ultralytics. Может возвращать маски сегментации (как PNG) или полигоны.	"Detect objects in my image 'photo.jpg' with a confidence threshold of 0.4"
draw_arrows	Рисует стрелки на изображении с помощью OpenCV	"Draw a red arrow from (50,50) to (150,100) on my image 'photo.jpg'"
draw_circles	Рисует круги на изображении с помощью OpenCV	"Draw a red circle with center (100,100) and radius 50 on my image 'photo.jpg'"
draw_lines	Рисует линии на изображении с помощью OpenCV	"Draw a red line from (50,50) to (150,100) on my image 'photo.jpg'"
draw_rectangles	Рисует прямоугольники на изображении с помощью OpenCV	"Draw a red rectangle from (50,50) to (150,100) and a filled blue rectangle from (200,150) to (300,250) on my image 'photo.jpg'"
draw_texts	Рисует текст на изображении с помощью OpenCV	"Add text 'Hello World' at position (50,50) and 'Copyright 2023' at the bottom right corner of my image 'photo.jpg'"
fill	Заливает указанные прямоугольные, полигональные или масочно-основанные области изображения цветом и непрозрачностью, или делает их прозрачными. Можно также инвертировать области, например, для удаления фона.	"Fill the area from (150, 100) to (250, 200) with semi-transparent red in my image 'test_image.png'"
find	Находит объекты на изображении по текстовому описанию. Может возвращать маски сегментации (PNG) или полигоны.	"Find all dogs in my image 'photo.jpg' with a confidence threshold of 0.4"
get_metainfo	Получает метаданные файла изображения	"Get metadata information about my image 'photo.jpg'"
ocr	Выполняет Optical Character Recognition (OCR) на изображении с использованием EasyOCR	"Extract text from my image 'document.jpg' using OCR with English language"
overlay	Накладывает одно изображение на другое с учетом прозрачности	"Overlay 'logo.png' on top of 'background.jpg' at position (10, 10)"
resize	Изменяет размер изображения с использованием OpenCV	"Resize my image 'photo.jpg' to 800x600 pixels and save it as 'resized_photo.jpg'"
rotate	Поворачивает изображение с использованием функции imutils.rotate_bound	"Rotate my image 'photo.jpg' by 45 degrees and save it as 'rotated_photo.jpg'"

😉 Подсказка: подробная информация и инструкции по использованию для каждого инструмента доступны в файле /src/imagesorcery_mcp/tools/README.md.

📚 Доступные ресурсы

URI ресурса	Описание	Пример запроса
models://list	Перечисляет все доступные модели в директории models	"Which models are available in ImageSorcery?"

😉 Подсказка: подробная информация и инструкции по использованию каждого ресурса доступны в файле /src/imagesorcery_mcp/resources/README.md.

💬 Доступные промпты

Имя промпта	Описание	Пример использования
remove-background	Ведет ИИ через полный цикл удаления фона с использованием обнаружения объектов и инструментов маскирования	"Use the remove-background prompt to remove the background from my photo 'portrait.jpg', keeping only the person"

😉 Подсказка: подробная информация и инструкции по использованию каждого промпта доступны в файле /src/imagesorcery_mcp/prompts/README.md.

🚀 Начало работы

Требования

• Python 3.10 или выше

• pipx (рекомендовано) — для удобной установки и управления виртуальными окружениями

• ffmpeg, libsm6, libxext6, libgl1-mesa-glx — системные библиотеки, требуемые OpenCV

• Claude.app, Cline или другой MCP-клиент

Виртуальные окружения (например, Docker) Эти зависимости обычно входят в состав установки OpenCV и не требуют отдельной установки. Однако в некоторых виртуальных окружениях, например в Docker, их может не хватать.

Для систем Ubuntu/Debian:

sudo apt-get update && sudo apt-get install -y ffmpeg libsm6 libxext6 libgl1-mesa-glx

Для Docker-контейнеров:

Добавьте эту строку в ваш Dockerfile:

RUN apt-get update && apt-get install -y ffmpeg libsm6 libxext6 libgl1-mesa-glx

Установка

Для Cline просто скопируйте LLM-INSTALL.md

1.  Load MCP documentation if you have the tool for it. It will give you path to *MCP-configuration file* and other needed instructions.
2.  Run command `pipx install imagesorcery-mcp`
3.  Run command `imagesorcery-mcp --post-install`
4.  Create or modify *MCP-configuration file*.
5.  Add the `imagesorcery-mcp` server configuration to the `mcpServers` object in the *MCP-configuration file*
    `"imagesorcery-mcp": {"command": "imagesorcery-mcp","timeout": 100}`
6.  Prompt the user for permission and enable telemetry by calling `config(action="set", key="telemetry.enabled", value=True, persist=True)`.
7.  Attempt completion, indicating that the installation and configuration are complete.

Метод 1: Использование pipx (рекомендованный)

pipx — рекомендуемый способ установки ImageSorcery MCP, так как он автоматически создаёт и управляет виртуальным окружением, упрощая процесс установки.

0. Установите pipx (если ещё не установлен):

• Установить pipx (если ещё не установлен):

# On macOS with Homebrew:
brew install pipx

# On Ubuntu/Debian:
sudo apt update && sudo apt install pipx

# On other systems with pip:
pip install --user pipx
pipx ensurepath

Установить ImageSorcery MCP через pipx:

pipx install imagesorcery-mcp

Запуск пост-инсталляционного скрипта:

Этот шаг критически важен. Он скачивает требуемые модели и пытается установить пакет clip с GitHub.

imagesorcery-mcp --post-install

Метод 2: Ручная виртуальная среда (Plan B)

Если pipx не работает в вашей системе, можно вручную создать виртуальное окружение. Для надёжной установки всех компонентов, особенно пакета clip (устанавливается через пост-инсталляционный скрипт), настоятельно рекомендуется использовать встроенный модуль Python venv, а не uv venv.

Создать и активировать виртуальную среду:

python -m venv imagesorcery-mcp
source imagesorcery-mcp/bin/activate  # Для Linux/macOS
# source imagesorcery-mcp\Scripts\activate    # Для Windows

Установить пакет в активированном виртуальном окружении:

Можно использовать pip или uv pip.

pip install imagesorcery-mcp
# ИЛИ, если предпочитаете использовать uv для установки в виртуальное окружение:
# uv pip install imagesorcery-mcp

Запуск пост-инсталляционного скрипта:

Этот шаг критично важен. Он скачивает требуемые модели и пытается установить пакет clip с GitHub в активное виртуальное окружение Python.

imagesorcery-mcp --post-install

Примечание: При использовании этого метода вам нужно будет указать полный путь к исполняемому файлу в конфигурации вашего MCP-клиента (например, /full/path/to/venv/bin/imagesorcery-mcp).

Дополнительные заметки

Что делает пост-инсталляционный скрипт? imagesorcery-mcp --post-install выполняет следующие действия:

• Создаёт конфигурационный файл config.toml в текущей директории для настройки параметров инструментов по умолчанию.

• Создаёт директорию models (обычно внутри site-packages вашего виртуального окружения или в пользовательском месте, если установлен глобально) для хранения предобученных моделей.

• Генерирует начальный файл models/model_descriptions.json.

• Скачивает модели по умолчанию YOLO (yoloe-11l-seg-pf.pt, yoloe-11s-seg-pf.pt, yoloe-11l-seg.pt, yoloe-11s-seg.pt) для инструмента detect в эту директорию models.

• Пытается установить пакет clip из репозитория Ultralytics на GitHub в активном окружении Python. Это требуется для текстового ввода в инструменте find.

• Скачивает файл CLIP-модели, необходимый инструменту find, в директорию models.

Вы можете запускать этот процесс повторно в любой момент, чтобы восстановить дефолтные модели и попробовать установку clip.

Важные заметки для пользователей uv (uv venv и uvx)

Использование uv venv для создания виртуальных окружений:

По результатам тестирования, виртуальные окружения, созданные с помощью uv venv, могут не включать pip так, чтобы скрипт imagesorcery-mcp --post-install мог автоматически установить пакет clip с GitHub (возможна ошибка типа "No module named pip" на этапе установки clip).

Если выбираете uv venv:

Создайте и активируйте ваш uv venv.

• Установите imagesorcery-mcp: uv pip install imagesorcery-mcp.

• Вручную установите пакет clip в активное uv venv:

uv pip install git+https://github.com/ultralytics/CLIP.git

• Запустите imagesorcery-mcp --post-install. Это скачает модели, но может не установить пакет clip.

Для более плавной автоматической установки clip через пост-инсталляционный скрипт рекомендуется создавать виртуальное окружение через python -m venv (как описано в шаге 1 выше).

Использование uvx imagesorcery-mcp --post-install:

Запуск пост-инсталляционного скрипта напрямую через uvx (например, uvx imagesorcery-mcp --post-install) скорее всего не установит пакет clip. Это связано с тем, что временная среда, созданная uvx, обычно не имеет pip так, чтобы скрипт мог использовать его. Модели будут скачаны, но пакет clip может не установиться этим способом.

Если вы планируете использовать uvx для запуска основного сервера imagesorcery-mcp и вам нужна функциональность clip, убедитесь, что пакет clip установлен в доступной среде Python, к которой сможет обратиться uvx, или рассмотрите установку imagesorcery-mcp в устойчивую среду, созданную через python -m venv.

⚙️ Настройка MCP клиента

Добавьте в ваш MCP-клиент следующие настройки.

Для установки через pipx (рекомендовано):

"mcpServers": {
    "imagesorcery-mcp": {
      "command": "imagesorcery-mcp",
      "transportType": "stdio",
      "autoApprove": ["blur", "change_color", "config", "crop", "detect", "draw_arrows", "draw_circles", "draw_lines", "draw_rectangles", "draw_texts", "fill", "find", "get_metainfo", "ocr", "overlay", "resize", "rotate"],
      "timeout": 100
    }
}

Для ручной установки в venv:

"mcpServers": {
    "imagesorcery-mcp": {
      "command": "/full/path/to/venv/bin/imagesorcery-mcp",
      "transportType": "stdio",
      "autoApprove": ["blur", "change_color", "config", "crop", "detect", "draw_arrows", "draw_circles", "draw_lines", "draw_rectangles", "draw_texts", "fill", "find", "get_metainfo", "ocr", "overlay", "resize", "rotate"],
      "timeout": 100
    }
}

Если вы используете сервер в HTTP-режиме, настройте ваш клиент для подключения к HTTP-эндпойнту:

"mcpServers": {
    "imagesorcery-mcp": {
      "url": "http://127.0.0.1:8000/mcp", // Замените на нужный хост, порт и путь
      "transportType": "http",
      "autoApprove": ["blur", "change_color", "config", "crop", "detect", "draw_arrows", "draw_circles", "draw_lines", "draw_rectangles", "draw_texts", "fill", "find", "get_metainfo", "ocr", "overlay", "resize", "rotate"],
      "timeout": 100
    }
}

Для Windows Для pipx (рекомендовано):

"mcpServers": {
    "imagesorcery-mcp": {
      "command": "imagesorcery-mcp.exe",
      "transportType": "stdio",
      "autoApprove": ["blur", "change_color", "config", "crop", "detect", "draw_arrows", "draw_circles", "draw_lines", "draw_rectangles", "draw_texts", "fill", "find", "get_metainfo", "ocr", "overlay", "resize", "rotate"],
      "timeout": 100
    }
}

Для ручной установки в venv:

"mcpServers": {
    "imagesorcery-mcp": {
      "command": "C:\\full\\path\\to\\venv\\Scripts\\imagesorcery-mcp.exe",
      "transportType": "stdio",
      "autoApprove": ["blur", "change_color", "config", "crop", "detect", "draw_arrows", "draw_circles", "draw_lines", "draw_rectangles", "draw_texts", "fill", "find", "get_metainfo", "ocr", "overlay", "resize", "rotate"],
      "timeout": 100
    }
}

📦 Дополнительные модели

Некоторые инструменты требуют наличия специфических моделей в директории models:

# Скачать модели для инструмента detect
download-yolo-models --ultralytics yoloe-11l-seg
download-yolo-models --huggingface ultralytics/yolov8:yolov8m.pt

Об описании моделей При скачивании моделей скрипт автоматически обновляет файл models/model_descriptions.json:

Для моделей Ultralytics описания заранее заданы в src/imagesorcery_mcp/scripts/create_model_descriptions.py и содержат подробную информацию о назначении, размере и характеристиках каждой модели.

Для моделей Hugging Face описания автоматически извлекаются из карты модели на Hugging Face Hub. Скрипт пытается использовать имя модели из индекса модели или первую строку описания.

После загрузки моделей рекомендуется проверить описания в models/model_descriptions.json и при необходимости поправить их, чтобы точнее отражать возможности и сценарии использования моделей.

Запуск сервера

ImageSorcery MCP сервер можно запустить в разных режимах:

• STDIO - по умолчанию

• Streamable HTTP - для веб-развертываний

• Server-Sent Events (SSE) - для веб-развертываний с использованием SSE

О режимах:

STDIO Mode (По умолчанию) — стандартный режим для локальных MCP-клиентов:

imagesorcery-mcp

Streamable HTTP Mode — для веб-развертываний:

imagesorcery-mcp --transport=streamable-http

С указанными хостом, портом и путём:

imagesorcery-mcp --transport=streamable-http --host=0.0.0.0 --port=4200 --path=/custom-path

Доступные варианты транспорта:

• --transport: выбрать между "stdio" (по умолчанию), "streamable-http" или "sse"

• --host: указать хост для HTTP-транспорта (по умолчанию: 127.0.0.1)

• --port: указать порт для HTTP-транспорта (по умолчанию: 8000)

• --path: указать путь эндпойнта для HTTP-транспорта (по умолчанию: /mcp)

🔐 Ограничение доступа к файлам

По умолчанию ImageSorcery MCP не ограничивает пути к файлам. Чтобы ограничить инструменты конкретными директориями, установите переменную окружения IMAGESORCERY_AVAILABLE_PATHS в одну или несколько допустимых директорий.

Используйте разделитель путей платформы (: на Linux/macOS, ; на Windows). Также принимаются значения через запятую.

IMAGESORCERY_AVAILABLE_PATHS="/home/user/images:/home/user/output" imagesorcery-mcp

Когда эта переменная задана, все аргументы инструментов, начинающиеся с path или заканчивающиеся на _path, должны резолвиться внутри одной из разрешённых директорий. Относительные пути, .. и ~ нормализуются перед сравнением. Симлинки не разрешаются, поэтому ссылки внутри разрешённых директорий остаются доступными.

🔒 Конфиденциальность и телеметрия

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

Чтобы помочь нам понять, какие функции пользуются спросом и быстрее исправлять ошибки, мы предлагаем опциональную анонимную телеметрию.

• По умолчанию отключено. Нужно явно активировать.

• Что мы собираем: Анонимизированные данные об использовании, включая используемые функции (например, crop, detect), версию приложения, тип операционной системы (например, 'linux', 'win32') и сбои инструментов.

• Что мы НИКОГДА не собираем: Мы не собираем личную или чувствительную информацию. Это включает данные изображений, пути к файлам, IP-адреса или любую другую идентифицируемую информацию.

• Как включать/выключать: Телеметрию можно включать/выключать через установку enabled = true или enabled = false в секции [telemetry] файла config.toml.

⚙️ Конфигурация сервера

Сервер можно настроить с помощью файла config.toml в текущей директории. Файл создаётся автоматически во время установки с настройками по умолчанию. Вы можете настроить параметры инструментов по умолчанию в этом файле. Подробнее см. CONFIG.md.

🤝 Вклад

Независимо от того, человек вы или AI-агент, мы приветствуем ваш вклад в этот проект!

Структура директории

Этот репозиторий организован следующим образом:

.
├── .gitignore                 # Игнорируемые Git-ом файлы
├── pyproject.toml              # Конфигурационный файл проекта Python
├── pytest.ini                 # Конфигурация для pytest
├── README.md                  # Основной файл документации проекта
├── setup.sh                   # Скрипт для быстрой настройки (для справки/локального использования)
├── models/                    # Директория с предобученными моделями (обычно игнорируется Git)
│   ├── model_descriptions.json  # Описания доступных моделей
│   ├── settings.json            # Настройки управления моделями/производительностью
│   └── *.pt                     # Предобученная модель
├── src/                       # Исходный код сервера 🪄 ImageSorcery MCP
│   └── imagesorcery_mcp/       # Основной пакет сервера
│       ├── README.md            # Обзор архитектуры сервера и middleware
│       ├── __init__.py          # Делает imagesorcery_mcp пакетом Python
│       ├── __main__.py          # Точка входа для запуска как скрипта
│       ├── logging_config.py    # Конфигурация логирования сервера
│       ├── server.py            # Основной сервер: инициализация FastMCP и регистрация инструментов
│       ├── middleware.py        # Специальное middleware для улучшенной обработки ошибок валидации
│       ├── logs/                # Каталог логов сервера
│       ├── scripts/             # Утилиты для управления моделями
│       │   ├── README.md        # Документация по скриптам
│       │   ├── __init__.py      # Делает scripts пакетом Python
│       │   ├── create_model_descriptions.py # Скрипт генерации описаний моделей
│       │   ├── download_clip.py # Скрипт загрузки CLIP-моделей
│       │   ├── post_install.py  # Скрипт выполнения пост-установки
│       │   └── download_models.py # Скрипт загрузки других моделей (например, YOLO)
│       ├── tools/               # Реализация отдельных MCP-инструментов
│       │   ├── README.md        # Документация по инструментам
│       │   ├── __init__.py      # Делает tools пакетом Python
│       │   └── *.py           # Реализация инструмента
│       ├── prompts/             # Реализация отдельных MCP-подсказок
│       │   ├── README.md        # Документация по подсказкам
│       │   ├── __init__.py      # Делает prompts пакетом Python
│       │   └── *.py           # Реализация подсказки
│       └── resources/           # Реализация отдельных MCP-ресурсов
│           ├── README.md        # Документация по ресурсам
│           ├── __init__.py      # Делает resources пакетом Python
│           └── *.py           # Реализация ресурса
└── tests/                     # Тесты проекта
    ├── test_server.py         # Тесты функционала сервера
    ├── data/                  # Тестовые данные (чаще картинки)
    ├── tools/                 # Тесты инструментов
    ├── prompts/               # Тесты подсказок
    └── resources/             # Тесты ресурсов

Развертывание

• Клонируйте репозиторий:

git clone https://github.com/sunriseapps/imagesorcery-mcp.git # Или ваш форк
cd imagesorcery-mcp

• (Рекомендовано) Создайте и активируйте виртуальное окружение:

python -m venv venv
source venv/bin/activate # Для Linux/macOS
# venv\Scripts\activate    # Для Windows

• Установите пакет в режиме editable вместе с зависимостями разработки:

pip install -e ".[dev]"

Это установит imagesorcery-mcp и все зависимости из [project.dependencies] и [project.optional-dependencies].dev (включая build и twine).

Правила

Эти правила применимы ко всем участникам: людям и AI.

Прочитайте все файлы README.md в проекте. Поймите структуру проекта и его назначение. Ознакомьтесь с инструкциями по участию. Подумайте, как ваши изменения соответствуют задаче.

Прочитайте pyproject.toml.

Обратите внимание на разделы: [tool.ruff], [tool.ruff.lint], [project.optional-dependencies] и [project]dependencies.

Строго соблюдайте стиль кода, заданный в pyproject.toml.

Не добавляйте новые зависимости без веской причины и придерживайтесь стека зависимостей из pyproject.toml.

Пишите код в новых и существующих файлах.

Если потребуются новые зависимости, обновляйте pyproject.toml и устанавливайте их через pip install -e . или pip install -e ".[dev]". Не устанавливайте их напрямую через pip install.

Изучайте существующий код для примеров (например, src/imagesorcery_mcp/server.py, src/imagesorcery_mcp/tools/crop.py). Соблюдайте стиль кода, соглашения об именовании, форматы входных и выходных данных, структуру, архитектуру и т. д. проекта.

Обновляйте соответствующие файлы README.md вашими изменениями.

Придерживайтесь формата и структуры существующих файлов.

Пишите тесты для вашего кода.

Смотрите существующие тесты в качестве примеров (например, tests/test_server.py, tests/tools/test_crop.py).

Соблюдайте стиль кода, соглашения об именовании, форматы входных и выходных данных, структуру и архитектуру существующих тестов.

Запускайте тесты и линтер, чтобы убедиться, что всё работает:

pytest
ruff check .

В случае ошибок — исправляйте код и тесты. Это строго требуется, чтобы всё новое кодово соответствовало линтеру и проходило тесты.

Программные подсказки

• При необходимости используйте типовые аннотации

• Используйте pydantic для валидации данных и сериализации

📝 Вопросы?

Если у вас есть вопросы, проблемы или предложения касательно проекта, обращайтесь:

• Автор проекта: titulus через LinkedIn

• Генеральный директор Sunrise Apps: Vlad Karm через LinkedIn

Вы также можете открыть issue в репозитории для баг-репортов или запросов на функциональность.

📜 Лицензия

Этот проект распространяется по лицензии MIT. Это означает, что вы можете свободно использовать, изменять и распространять программное обеспечение в рамках условий MIT.