playbooks
Learn Cursor Rules Windsurf Rules MCPs Modes
Log in

ImageSorcery MCP server

Provides powerful image manipulation capabilities including resizing, cropping, object detection, OCR text extraction, and finding objects based on text descriptions using Python with OpenCV and Ultralytics
Back to servers
Setup instructions
Provider
Sunrise Apps
Release date
May 23, 2025
Language
Python
Stats
89 stars
View on GitHub

ImageSorcery MCP empowers AI assistants with advanced image processing capabilities, allowing them to analyze, modify, and interact with images. Through a set of specialized tools, it enables operations like cropping, text extraction, object detection, and drawing on images - all accessible through natural language requests.

Installation

Requirements

  • Python 3.10 or higher
  • Claude.app, Cline, or another MCP client

Setting Up the Environment

Create and activate a virtual environment (strongly recommended):

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

Installing the Package

Install the package into the activated virtual environment:

pip install imagesorcery-mcp

Post-Installation Setup

Run the post-installation script to download required models:

imagesorcery-mcp --post-install

This script performs several important tasks:

  • Creates a models directory to store pre-trained models
  • Generates initial model configuration files
  • Downloads default YOLO models required by the detect tool
  • Installs the clip Python package for text prompt functionality
  • Downloads the CLIP model required by the find tool

Important Notes for uv Users

If using uv venv to create virtual environments, you may need to manually install the clip package:

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

Configuration

MCP Client Configuration

Add the following settings to your MCP client configuration:

For standard installation (with imagesorcery-mcp in PATH):

"mcpServers": {
    "imagesorcery-mcp": {
      "command": "imagesorcery-mcp", 
      "transportType": "stdio",
      "autoApprove": ["detect", "crop", "get_models", "draw_texts", "get_metainfo", "rotate", "resize", "classify", "draw_rectangles", "find", "ocr"],
      "timeout": 100
    }
}

For venv installation (specify full path):

"mcpServers": {
    "imagesorcery-mcp": {
      "command": "/full/path/to/venv/bin/imagesorcery-mcp",
      "transportType": "stdio",
      "autoApprove": ["detect", "crop", "get_models", "draw_texts", "get_metainfo", "rotate", "resize", "classify", "draw_rectangles", "find", "ocr"],
      "timeout": 100
    }
}

For HTTP mode:

"mcpServers": {
    "imagesorcery-mcp": {
      "url": "http://127.0.0.1:8000/mcp",
      "transportType": "http",
      "autoApprove": ["detect", "crop", "get_models", "draw_texts", "get_metainfo", "rotate", "resize", "classify", "draw_rectangles", "find", "ocr"],
      "timeout": 100
    }
}

For Windows:

"mcpServers": {
    "imagesorcery-mcp": {
      "command": "imagesorcery-mcp.exe", 
      "transportType": "stdio",
      "autoApprove": ["detect", "crop", "get_models", "draw_texts", "get_metainfo", "rotate", "resize", "classify", "draw_rectangles", "find", "ocr"],
      "timeout": 100
    }
}

Adding 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

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

Running the Server

ImageSorcery MCP server can be run in different modes:

STDIO Mode (Default)

For standard local MCP clients:

imagesorcery-mcp

HTTP Mode

For web-based deployments:

imagesorcery-mcp --transport streamable-http

With custom host, port, and path:

imagesorcery-mcp --transport streamable-http --host 0.0.0.0 --port 9000 --path /mcp-api

Available Tools

Blur

Blurs specified areas of an image using 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'"

Crop

Crops an image using OpenCV's NumPy slicing approach:

"Crop my image 'input.png' from coordinates (10,10) to (200,200) and save it as 'cropped.png'"

Detect

Detects objects in an image using models from Ultralytics:

"Detect objects in my image 'photo.jpg' with a confidence threshold of 0.4"

Draw Rectangles

Draws rectangles on an image using 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

Draws text on an image using OpenCV:

"Add text 'Hello World' at position (50,50) and 'Copyright 2023' at the bottom right corner of my image 'photo.jpg'"

Find

Finds objects in an image based on a text description:

"Find all dogs in my image 'photo.jpg' with a confidence threshold of 0.4"

Get Metainfo

Gets metadata information about an image file:

"Get metadata information about my image 'photo.jpg'"

Get Models

Lists all available models in the models directory:

"List all available models in the models directory"

OCR

Performs Optical Character Recognition (OCR) on an image using EasyOCR:

"Extract text from my image 'document.jpg' using OCR with English language"

Resize

Resizes an image using OpenCV:

"Resize my image 'photo.jpg' to 800x600 pixels and save it as 'resized_photo.jpg'"

Rotate

Rotates an image using imutils.rotate_bound function:

"Rotate my image 'photo.jpg' by 45 degrees and save it as 'rotated_photo.jpg'"

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "imagesorcery-mcp" '{"command":"imagesorcery-mcp","transportType":"stdio","autoApprove":["detect","crop","get_models","draw_texts","get_metainfo","rotate","resize","classify","draw_rectangles","find","ocr"],"timeout":100}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "imagesorcery-mcp": {
            "command": "imagesorcery-mcp",
            "transportType": "stdio",
            "autoApprove": [
                "detect",
                "crop",
                "get_models",
                "draw_texts",
                "get_metainfo",
                "rotate",
                "resize",
                "classify",
                "draw_rectangles",
                "find",
                "ocr"
            ],
            "timeout": 100
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "imagesorcery-mcp": {
            "command": "imagesorcery-mcp",
            "transportType": "stdio",
            "autoApprove": [
                "detect",
                "crop",
                "get_models",
                "draw_texts",
                "get_metainfo",
                "rotate",
                "resize",
                "classify",
                "draw_rectangles",
                "find",
                "ocr"
            ],
            "timeout": 100
        }
    }
}

3. Restart Claude Desktop for the changes to take effect

Want to 10x your AI skills?

Get a free account and learn to code + market your apps using AI (with or without vibes!).

Nah, maybe later