🪄 ImageSorcery MCP

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

Official website: imagesorcery.net

✅ With ImageSorcery MCP

🪄 ImageSorcery empowers AI assistants with powerful image processing capabilities:

• ✅ Crop, resize, and rotate images with precision
• ✅ Remove background
• ✅ Draw text and shapes on images
• ✅ Add logos and watermarks
• ✅ Detect objects using state-of-the-art models
• ✅ Extract text from images with OCR
• ✅ Use a wide range of pre-trained models for object detection, OCR, and more
• ✅ Do all of this locally, without sending your images to any servers

Just ask your AI to help with image tasks:

“copy photos with pets from folder 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 centered” 😉 Hint: Use full path to your files".

“Enumerate 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: Specify the model and the confidence".

😉 Hint: Add “use imagesorcery” to make sure it will use the proper tool".

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

🛠️ Available Tools

😉 Hint: detailed information and usage instructions for each tool can be found in the tool’s /src/imagesorcery_mcp/tools/README.md.

📚 Available Resources

😉 Hint: detailed information and usage instructions for each resource can be found in the resource’s /src/imagesorcery_mcp/resources/README.md.

💬 Available Prompts

😉 Hint: detailed information and usage instructions for each prompt can be found in the prompt’s /src/imagesorcery_mcp/prompts/README.md.

🚀 Getting Started

Requirements

• Python 3.10 or higher
• pipx (recommended) - for easy installation and virtual environment management
• ffmpeg, libsm6, libxext6, libgl1-mesa-glx - system libraries required by OpenCV
• Claude.app, Cline, or another MCP client

Installation

Method 1: Using pipx (Recommended)

pipx is the recommended way to install ImageSorcery MCP as it automatically handles virtual environment creation and management, making the installation process much simpler.

1. Install ImageSorcery MCP with pipx:

   pipx install imagesorcery-mcp
   

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

   imagesorcery-mcp --post-install
   

Method 2: Manual Virtual Environment (Plan B)

Additional Notes

⚙️ Configure MCP client

Add to your MCP client these settings.

For pipx installation (recommended):

"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
    }
}

For manual venv installation:

"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
    }
}

📦 Additional Models

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

# Download models for the detect tool
download-yolo-models --ultralytics yoloe-11l-seg
download-yolo-models --huggingface ultralytics/yolov8:yolov8m.pt

Running the Server

ImageSorcery MCP server can be run in different modes:

• STDIO - default
• Streamable HTTP - for web-based deployments
• Server-Sent Events (SSE) - for web-based deployments that rely on SSE

🔐 File Access Restrictions

By default, ImageSorcery MCP does not restrict file paths. To limit tools to specific directories, set IMAGESORCERY_AVAILABLE_PATHS to one or more allowed directories.

Use the platform path-list separator (: on Linux/macOS, ; on Windows). Comma-separated values are also accepted.

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

When this variable is set, all tool arguments named path or ending with _path must resolve inside one of the allowed directories. Relative paths, .., and ~ are normalized before comparison. Symlinks are not resolved, so links placed inside allowed directories remain accessible.

🔒 Privacy & Telemetry

We are committed to your privacy. ImageSorcery MCP is designed to run locally, ensuring your images and data stay on your machine.

To help us understand which features are most popular and fix bugs faster, we’ve included optional, anonymous telemetry.

• It is disabled by default. You must explicitly opt-in to enable it.
• What we collect: Anonymized usage data, including features used (e.g., crop, detect), application version, operating system type (e.g., ‘linux’, ‘win32’), and tool failures.
• What we NEVER collect: We do not collect any personal or sensitive information. This includes image data, file paths, IP addresses, or any other personally identifiable information.
• How to enable/disable: You can control telemetry by setting enabled = true or enabled = false in the [telemetry] section of your config.toml file.

⚙️ Configuring the Server

The server can be configured using a config.toml file in the current directory. The file is created automatically during installation with default values. You can customize the default tool parameters in this file. More in CONFIG.md.

🤝 Contributing

📝 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.