🪄 ImageSorcery MCP

ComputerVision-based 🪄 sorcery of image recognition and editing tools for AI assistants

❌ Without ImageSorcery MCP

AI assistants are limited when working with images:

• ❌ Can't modify or analyze images directly

• ❌ No ability to crop, resize, or process images

• ❌ Some LLMs can't detect objects or extract text from images

• ❌ Limited to verbal descriptions with no visual manipulation

✅ With ImageSorcery MCP

🪄 ImageSorcery empowers AI assistants with powerful image processing capabilities:

• ✅ Crop, resize, and rotate images with precision

• ✅ Draw text and shapes on images

• ✅ Detect objects using state-of-the-art models

• ✅ Extract text from images with OCR

• ✅ Get detailed image metadata

• ✅ Use a wide range of pre-trained models for object detection, OCR, and more

Just ask your AI to help with image tasks:

"copy photos with pets from frolder photos to folder pets"

"Find a cat at the photo.jpg and crop the image in a half in height and width to make the cat be centerized" 😉 Hint:

"Numerate form fields on this form.jpg with foduucom/web-form-ui-field-detection model and fill the form.md with a list of described fields" 😉 Hint:

😉 Hint:

Your tool will combine multiple tools listed below to achieve your goal.

🛠️ Available Tools

😉 Hint:

🚀 Getting Started

Requirements

• Python 3.10 or higher

• Claude.app, Cline, or another MCP client

Installation

1. Create and activate a virtual environment (Strongly Recommended): For reliable installation of all components, especially the clip package (installed via the post-install script), it is strongly recommended to use Python's built-in .

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

2. Install the package into the activated virtual environment: You can use pip or uv pip.

   pip install imagesorcery-mcp # OR, if you prefer using uv for installation into the venv: # uv pip install imagesorcery-mcp

3. Run the post-installation script: This step is crucial. It downloads the required models and attempts to install the clip Python package from GitHub into the active virtual environment.

   imagesorcery-mcp --post-install

• Creates a models directory (usually within the site-packages directory of your virtual environment, or a user-specific location if installed globally) to store pre-trained models.

• Generates an initial models/model_descriptions.json file there.

• Downloads default YOLO models (yoloe-11l-seg-pf.pt, yoloe-11s-seg-pf.pt, yoloe-11l-seg.pt, yoloe-11s-seg.pt) required by the detect tool into this models directory.

• Attempts to install the from Ultralytics' GitHub repository directly into the active Python environment. This is required for text prompt functionality in the find tool.

• Downloads the CLIP model file required by the find tool into the models directory.

You can run this process anytime to restore the default models and attempt clip installation.

• Using Based on testing, virtual environments created with uv venv may not include pip in a way that allows the imagesorcery-mcp --post-install script to automatically install the clip package from GitHub (it might result in a "No module named pip" error during the clip installation step). If you choose to use

  1. Create and activate your uv venv.

  2. Install imagesorcery-mcp: uv pip install imagesorcery-mcp.

  3. Manually install the clip package into your active uv venv:

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

  4. Run imagesorcery-mcp --post-install. This will download models but may fail to install the clip Python package. For a smoother automated clip installation via the post-install script, using python -m venv (as described in step 1 above) is the recommended method for creating the virtual environment.

• Using Running the post-installation script directly with uvx (e.g., uvx imagesorcery-mcp --post-install) will likely fail to install the clip Python package. This is because the temporary environment created by uvx typically does not have pip available in a way the script can use. Models will be downloaded, but the clip package won't be installed by this command. If you intend to use uvx to run the main imagesorcery-mcp server and require clip functionality, you'll need to ensure the clip package is installed in an accessible Python environment that uvx can find, or consider installing imagesorcery-mcp into a persistent environment created with python -m venv.

⚙️ Configuration MCP client

Add to your MCP client these settings. If imagesorcery-mcp is in your system's PATH after installation, you can use imagesorcery-mcp directly as the command. Otherwise, you'll need to provide the full path to the executable.

📦 Additional Models

Some tools require specific models to be available in the models directory:

When downloading models, the script automatically updates the models/model_descriptions.json file:

• For Ultralytics models: Descriptions are predefined in src/imagesorcery_mcp/scripts/create_model_descriptions.py and include detailed information about each model's purpose, size, and characteristics.

• For Hugging Face models: Descriptions are automatically extracted from the model card on Hugging Face Hub. The script attempts to use the model name from the model index or the first line of the description.

After downloading models, it's recommended to check the descriptions in models/model_descriptions.json and adjust them if needed to provide more accurate or detailed information about the models' capabilities and use cases.

🤝 Contributing

Directory Structure

This repository is organized as follows:

Development Setup

1. Clone the repository:

2. (Recommended) Create and activate a virtual environment:

3. Install the package in editable mode along with development dependencies:

This will install imagesorcery-mcp and all dependencies from [project.dependencies] and [project.optional-dependencies].dev (including build and twine).

Rules

These rules apply to all contributors: humans and AI.

1. Read all the README.md files in the project. Understand the project structure and purpose. Understand the guidelines for contributing. Think through how it's relate to you task, and how to make changes accordingly.

2. Read pyproject.toml. Make attention to sections: [tool.ruff], [tool.ruff.lint], [project.optional-dependencies] and [project]dependencies. Strictly follow code style defined in pyproject.toml. Stick to the stack defined in pyproject.toml dependencies and do not add any new dependencies without a good reason.

3. Write your code in new and existing files. If new dependencies needed, update pyproject.toml and install them via pip install -e . or pip install -e ".[dev]". Do not install them diirectly via pip install. Check out exixisting source codes for examples (e.g. src/imagesorcery_mcp/server.py, src/imagesorcery_mcp/tools/crop.py). Stick to the code style, naming conventions, input and outpput data formats, codeode structure, arcchitecture, etc. of the existing code.

4. Update related README.md files with your changes. Stick to the format and structure of the existing README.md files.

5. Write tests for your code. Check out existing tests for examples (e.g. tests/test_server.py, tests/tools/test_crop.py). Stick to the code style, naming conventions, input and outpput data formats, codeode structure, arcchitecture, etc. of the existing tests.

6. Run tests and linter to ensure everything works:

In case of fails - fix the code and tests. It is strictly required to have all new code to comply with the linter rules and pass all tests.

Coding hints

• Use type hints where appropriate

• Use pydantic for data validation and serialization

📝 Questions?

If you have any questions, issues, or suggestions regarding this project, feel free to reach out to:

• Project Author: titulus via LinkedIn

• Sunrise Apps CEO: Vlad Karm via LinkedIn

You can also open an issue in the repository for bug reports or feature requests.

📜 License

This project is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License.