Overview

ImageSorcery MCP is a local Model Context Protocol (MCP) server that exposes a suite of computer vision and image editing tools for integration with AI assistants and developer workflows. It runs entirely on your machine, letting you perform object detection, segmentation, OCR, image transforms and compositing without sending image data to third‑party cloud services. Because it implements MCP, it can be plugged into assistants or tooling that speak the MCP protocol.

This server combines OpenCV-based image operations, EasyOCR for text extraction, and Ultralytics-style models for detection/segmentation into a single, modular toolset. Typical uses include automating image preprocessing pipelines, adding vision capabilities to assistants (e.g., “use ImageSorcery to detect and crop faces”), and batch image manipulation for privacy‑preserving workflows.

Features

Local image processing: crop, resize, rotate, blur, color transforms, fills, overlays
Image editing primitives: draw lines, arrows, rectangles, circles, and texts
Object detection and segmentation using pre-trained models (masks or polygons)
OCR via EasyOCR for multi-language text extraction
Background removal and mask-based fills
Resources management (models://) and configurable detection confidence
MCP server interface for integration with AI assistants and tools that support MCP
No external uploads — images remain on your machine

Installation / Configuration

Install via PyPI (recommended) or from source.

Install from PyPI:

python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install imagesorcery-mcp

Install from source:

git clone https://github.com/sunriseapps/imagesorcery-mcp.git
cd imagesorcery-mcp
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .

Running the MCP server

# Example: run via module entrypoint (adjust if your install exposes a CLI)
python -m imagesorcery_mcp.server --host 127.0.0.1 --port 3000

Basic configuration (JSON example)

{
  "host": "127.0.0.1",
  "port": 3000,
  "models_path": "/path/to/models",
  "default_detection_confidence": 0.4,
  "ocr_languages": ["en"]
}

Save this as imagesorcery_config.json and point the server to it with –config /path/to/imagesorcery_config.json or via an environment variable (consult the repository README for exact CLI flags).

Tip: Keep a local models directory and configure models_path to avoid redownloading models each run.

Available Tools

ImageSorcery exposes multiple tools (MCP tool names shown) for common computer vision tasks. Below is a condensed reference; see the project source for detailed per-tool options.

Tool	Purpose	Example prompt
blur	Blur regions or invert selection to blur background	“Blur area (150,100)-(250,200) with strength 21”
change_color	Apply palettes (sepia, grayscale, etc.)	“Convert to sepia”
crop	Crop images using pixel coordinates	“Crop (10,10)-(200,200)”
detect	Object detection / segmentation (masks or polygons)	“Detect objects with confidence ≥ 0.4”
fill	Fill or erase (transparent) specified areas or masks	“Make background transparent”
find	Find objects by text description (e.g., ‘dog’)	“Find all dogs”
ocr	Extract text using EasyOCR	“Extract English text”
overlay	Composite one image over another (handles alpha)	“Overlay logo.png at (10,10)”
resize, rotate	Resize and rotate images	“Rotate by 45 degrees”
draw_*	draw_arrows, draw_lines, draw_rectangles, draw_circles, draw_texts	“Draw red rectangle from …”, “Add watermark”
get_metainfo	Read file metadata	“Get metadata for photo.jpg”
config	Inspect/update ImageSorcery configuration	“Set default_detection_confidence to 0.8”

Resources

models://list — lists available local models and their URIs

Use Cases

Assistant-driven photo organization
- Prompt your assistant: “Use ImageSorcery: find all photos with cats in /photos, crop to the detected cat, and save to /photos/pets.”
- The MCP server can detect cats, produce cropping coordinates, and save new files locally.
Privacy-aware document processing (local OCR + redact)
- Run OCR on scans with the ocr tool, then blur or fill sensitive fields (SSNs, emails) before exporting PDFs.
Batch watermarking and branding
- Use overlay to add a logo to hundreds of images in a folder; resize and draw_texts can standardize size and captions.
Form field extraction and automated documentation
- Detect form fields with a detection model (e.g., a model for web form field detection), enumerate fields, and generate a Markdown inventory (form.md) describing detected fields and confidence scores.

Getting Help and Next Steps

Repository & issues: https://github.com/sunriseapps/imagesorcery-mcp
Read tool-specific READMEs in src/imagesorcery_mcp/tools for parameters and examples
Configure models and test detection thresholds to match your data

Run the server locally and test with a few images to tune model confidence and output formats (mask PNGs or polygons). Because ImageSorcery runs locally, it’s a good fit for privacy-sensitive workflows, offline automation, and assistant-enabled image tasks.

ImageSorcery MCP Server: Local Computer Vision Tools