ImageSorcery MCP

The ImageSorcery MCP Server allows your local AI assistant like Claude Code and Cursor to edit and analyze images directly on your local machine.

This means you can tell your AI assistant, in plain language, to perform tasks like cropping photos, removing backgrounds, or detecting objects, and it all happens privately on your computer. You don’t have to upload your images to any third-party service.

Key Features

• 🎯 Object detection with segmentation masks and polygon outputs
• 📝 OCR text extraction from images using EasyOCR
• ✂️ Basic image operations: crop, resize, rotate
• 🎨 Advanced editing: background removal, color changes, blur effects
• 📐 Drawing tools: arrows, circles, rectangles, text overlays
• 🔍 Text-based object finding using CLIP models
• 📊 Image metadata extraction
• 🖼️ Image overlaying and watermarking
• ⚙️ Configurable confidence thresholds and model settings

How To Use It

1. Install the package using pipx.

pipx install imagesorcery-mcp

2. Run the post-installation script.

imagesorcery-mcp --post-install

3. Add the ImageSorcery server to your MCP client’s configuration file. For an installation done with pipx, the configuration looks like this:

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

If you installed it manually into a virtual environment, you’ll need to provide the full path to the imagesorcery-mcp executable in the "command" field.

4. Once configured, you can start making requests to your AI assistant. For best results, be specific. For example:

• "use imagesorcery to find a cat in photo.jpg and crop the image to center the cat"
• "use imagesorcery to extract all text from document.png using OCR"

5. All available tools

FAQs

Q: The find tool isn’t working with text prompts. What’s wrong?
A: This is almost always because the clip Python package failed to install. The find tool relies on it to understand text prompts. Run imagesorcery-mcp --post-install again. If it still fails, especially if you use uv, you may need to install it manually into your active virtual environment with pip install git+https://github.com/ultralytics/CLIP.git.

Q: Why do I need to install system libraries like ffmpeg?
A: ImageSorcery uses OpenCV (cv2) under the hood for most of its image processing tasks. OpenCV, in turn, depends on these system-level libraries for handling various image and video codecs and for rendering windows. They are often missing in minimal environments like Docker containers.

Q: How do I add and use a new object detection model?
A: The project includes a script for this. You can download models from sources like Ultralytics or Hugging Face directly from the command line. For example: download-yolo-models --huggingface ultralytics/yolov8:yolov8m.pt. Once downloaded, the model will be registered in models/model_descriptions.json, and you can specify it in your prompts to the detect tool.

Q: Is the telemetry feature safe? Does it collect my image data?
A: The telemetry is completely safe and privacy-focused. It is disabled by default and you must explicitly opt-in. It NEVER collects any personal or sensitive data, including image data, file paths, or IP addresses. It only collects anonymized usage data (e.g., which tools are used, application version) to help the developers fix bugs and prioritize features.