Image Processor MCP
An open-source MCP server that gives AI assistants real image-processing hands - download, compress, batch-convert, rename, and read text from images, all through conversation.
Overview
Every website project ends with the same chore: a folder of oversized images that need converting, compressing, renaming, and re-referencing across the codebase. It's mechanical work - exactly the kind an AI assistant should handle. The problem: assistants can talk about images, but they couldn't touch them.
Image Processor MCP fixes that. It is a Model Context Protocol server, published on npm, that exposes six production-grade image tools to any MCP-capable assistant (Claude Desktop, VS Code extensions, and others). One `npx -y image-processor-mcp` line in a config file, and your assistant can download, compress, batch-convert, OCR, and keep your codebase in sync with renamed files.
Design goals
Local-first: OCR runs 100% on-machine via tesseract.js - image content never leaves your disk, and no API key is required.
Deterministic outputs an LLM can rely on: every tool returns structured results (sizes, ratios, quality steps, report paths) rather than prose.
Safety before speed: batch operations generate reports and mappings; filename sync is dry-run by default and refuses stale mapping files.
Real-world formats: 35+ input formats accepted, 10 output formats including WebP, AVIF, and JPEG XL.
The interesting engineering in an MCP server is rarely the happy path - it is making every edge case return something an LLM can act on instead of hallucinate around.
What It Does
download_image
Fetch an image from a URL or search Pexels by keyword - then optionally compress and convert it in the same call.
compress_image
Convert and compress a single image across 10 output formats, with recursive quality-stepping until it hits a target file size in KB.
compress_directory
Batch-process an entire directory recursively - structure preserved, filenames normalized, with an auto-generated markdown report and mappings file.
sync_filenames
Scan your codebase and rewrite every reference to renamed images - dry-run by default, with line-by-line previews before anything changes.
extract_text
OCR via tesseract.js in 100+ languages, running entirely on your machine - no cloud API, no key, no data leaving your disk.
get_acknowledgement
Self-documenting tool that returns the full configuration reference, so the assistant can teach itself the defaults.
How It Works
Installation is a single config entry. Any MCP-capable client picks the server up via npx - no global install, no build step:
{
"mcpServers": {
"image-processor-mcp": {
"command": "npx",
"args": ["-y", "image-processor-mcp"],
"env": { "IMAGE_SEARCH_API_KEY": "optional-pexels-key" }
}
}
}Recursive compression to a target size
The compression core solves a practical problem: "make this image under 100 KB without destroying it." The sharp pipeline applies the requested format and quality, measures the result, and - in recursive mode - steps quality down iteration by iteration until the target size is reached or a quality floor stops it. Explicit dimensions win; otherwise anything over the max dimension is scaled proportionally. In-place compression goes through a buffer so a failed write can never corrupt the original.
Batch processing with receipts
compress_directory walks a folder tree, converts every image while preserving structure, and normalizes filenames on the way. It then writes two artifacts: a markdown report of every file (before/after sizes, reduction percentages) and a JSON mappings file of old to new filenames. That mappings file feeds sync_filenames, which scans your project and rewrites every code reference - after showing a dry-run preview with per-line context. A mappings file without its matching report is rejected outright, so stale renames can never be replayed against a changed codebase.
OCR that respects your data
extract_text wraps tesseract.js with the production plumbing the library needs: a job queue that serializes recognition, worker reuse with automatic reinitialization when the language changes, worker recycling every 500 jobs, and crash recovery. Unsupported formats are auto-converted to PNG first; preprocessing applies grayscale and auto-rotation for better accuracy. Output comes back as plain text, positioned blocks, hOCR, or TSV - with confidence scores.
This site is proof the tool works: every generated image in the design system you're looking at was compressed through the same sharp pipeline this package productizes.
Built With
This is the engineering standard your project gets, too.
Let's TalkNext Case Study
