MCP Image Processor

An MCP server that provides tools for downloading, compressing, optimizing images, and extracting text via OCR. Built using the Model Context Protocol (MCP), this server enables AI assistants to download images from URLs or search, compress and convert images with various format options, batch process entire directories with auto-generated reports, synchronize filename references across your project, and extract printed text from images.

Features

• Download images from URLs or search by keyword (Pexels integration)
• Compress and convert single images with 10 output formats (WebP, AVIF, JPEG, PNG, TIFF, GIF, HEIF, JPEG 2000, JPEG XL, PDF)
• Recursive compression to target file size
• Lossless and lossy compression with configurable quality and CPU effort
• Auto-resize oversized images
• Batch process entire directories preserving folder structure
• Filename and directory name normalization (replace chars, case conversion)
• Auto-generated markdown compression reports with file tree, per-file details, and input vs output comparison
• Auto-generated filename mappings JSON paired with each compression report
• Scan project files and replace old filenames with new filenames using the mapping file
• OCR text extraction from images (100+ languages, region-specific, runs 100% locally)

Available Tools

download_image

Downloads an image from a URL or searches by keyword and downloads the result. Optionally applies compression, format conversion, and resizing in a single step.

Modes:

• URL mode: Provide a direct image URL via the url parameter.
• Search mode: Provide a keyword via the query parameter. Requires IMAGE_SEARCH_API_KEY environment variable to be set (get a free key at https://www.pexels.com/api/key/).

Parameters:

• url (optional): URL of the image to download. Required if query is not provided.
• query (optional): Search keyword to find an image. Required if url is not provided.
• outputPath (required): Path where to save the downloaded image.
• outputFormat (optional): Output format - webp, avif, jpeg, png, tiff, gif (default: keep original format)
• quality (optional): Compression quality 1-100 (default: 85)
• lossless (optional): Use lossless compression (default: false)
• effort (optional): CPU effort 0-6 (default: 6)
• width (optional): Exact target width
• height (optional): Exact target height
• maxDimension (optional): Auto-resize threshold in pixels (default: 2000)
• recursiveCompress (optional): Re-compress until under target size (default: false)
• expectedSizeKB (optional): Target file size in KB (default: 100)
• qualityStepDown (optional): Quality decrease per iteration (default: 10)
• minimumQualityFloor (optional): Minimum quality allowed (default: 10)

compress_image

Compresses or converts a single image with format conversion, quality adjustment, resizing, and optional recursive compression.

Parameters:

• inputPath (required): Path to the input image
• outputPath (required): Path to save the compressed image
• outputFormat (optional): Output format - webp, avif, jpeg, png, tiff, gif, heif, jp2, jxl, pdf (default: webp)
• quality (optional): Compression quality 1-100 (default: 85)
• lossless (optional): Use lossless compression (default: false)
• effort (optional): CPU effort 0-6 (default: 6)
• width (optional): Exact target width
• height (optional): Exact target height
• maxDimension (optional): Auto-resize threshold in pixels (default: 2000)
• recursiveCompress (optional): Re-compress until under target size (default: false)
• expectedSizeKB (optional): Target file size in KB (default: 100)
• qualityStepDown (optional): Quality decrease per iteration (default: 10)
• minimumQualityFloor (optional): Minimum quality allowed (default: 10)

compress_directory

Batch compresses all images in a directory recursively, preserving folder structure, with an auto-generated report.

Parameters:

• inputDir (required): Input directory containing images
• outputDir (required): Output directory for compressed images
• outputFormat (optional): Output format (default: webp)
• quality (optional): Compression quality 1-100 (default: 85)
• lossless (optional): Use lossless compression (default: false)
• effort (optional): CPU effort 0-6 (default: 6)
• maxDimension (optional): Auto-resize threshold (default: 2000)
• normalizeFilename (optional): Enable filename normalization
• filenameReplaceChars (optional): Characters to replace with underscore (comma-separated)
• filenameCase (optional): Filename case - lowercase, uppercase, original
• normalizeDirname (optional): Enable directory name normalization
• dirnameReplaceChars (optional): Characters to replace in directory names (comma-separated)
• dirnameCase (optional): Directory name case
• recursiveCompress (optional): Re-compress oversized outputs
• expectedSizeKB (optional): Target file size in KB (default: 100)
• qualityStepDown (optional): Quality decrease per iteration (default: 10)
• minimumQualityFloor (optional): Minimum quality floor (default: 10)

sync_filenames

Scan project files and replace all references to old filenames with new filenames after compression (e.g., PNG to WebP). Supports both file-based mappings from compress_directory and inline LLM-provided mappings as fallback.

Parameters:

• scanDir (required): Directory to scan for references
• mappingFilePath (optional): Path to a mappings JSON file generated by compress_directory. The file is timestamp-validated against its matching compression report before any replacements are applied.
• mappings (optional): Inline array of {oldFileName, newFileName} pairs. Fallback if mappingFilePath is not provided or unavailable.
• includeExtensions (optional): File extensions to scan (default: .html, .js, .ts, .css, .md, .json, etc.)
• excludeDirectories (optional): Directories to skip (default: node_modules, .git, build, dist)
• dryRun (optional): Preview only, no changes (default: true)

extract_text

Extracts visible printed text from images using OCR (tesseract.js). Runs entirely locally — no API keys, no cloud calls, no data leaves your machine.

Parameters:

• imagePath (required): Path to the image file
• language (optional): OCR language code (default: eng). Use "+" for multiple languages, e.g. "eng+chi_sim"
• rectangle (optional): Restrict OCR to a specific region of the image. Contains: top, left, width, height
• outputFormat (optional): Output format — text (default, plain string), blocks (JSON with positions), hocr (HTML-like), tsv (tab-separated)
• preprocess (optional): Auto-preprocess image for better OCR (grayscale + auto-rotate + resolution normalization, default: true)

Limitations:

• Handwritten text is NOT supported — Tesseract OCR is built for printed text only
• SVG files are rejected — vector formats have no raster pixels to OCR
• First run downloads language data (~2MB for English) from CDN, then caches locally

get_acknowledgement

Returns all configuration defaults, supported input/output formats with descriptions, and detailed parameter explanations for every tool.

Parameters: None

How sync_filenames Works

The recommended workflow uses a two-step process that avoids relying on the LLM to extract and pass mappings:

Step 1: compress_directory generates a mappings JSON file

When you run compress_directory, it creates two files in .image-processor-mcp/:

.image-processor-mcp/
  reports/
    scan-report-2026-05-22-18-30-00.md   (compression report)
  mappings/
    mappings-2026-05-22-18-30-00.json    (filename mappings JSON)

Both files share the exact same timestamp in their filename, ensuring they are always paired.

The mappings JSON file contains:

{
  "generatedAt": "2026-05-22T18:30:00.000Z",
  "tool": "compress_directory",
  "mappings": [
    { "oldFileName": "logo.png", "newFileName": "logo.webp" },
    { "oldFileName": "banner.jpg", "newFileName": "banner.avif" }
  ]
}

The compress_directory response also includes mappingsPath pointing to this file.

Step 2: sync_filenames reads the mapping file

Pass the mappingFilePath parameter pointing to the JSON file:

{
  "scanDir": "./src",
  "mappingFilePath": ".image-processor-mcp/mappings/mappings-2026-05-22-18-30-00.json",
  "dryRun": true
}

Before any replacements, sync_filenames validates that:

1. The mappings JSON file exists and has valid entries
2. A matching compression report (reports/scan-report-<same-timestamp>.md) exists

If the matching report does not exist, the tool rejects the operation — preventing stale or manually-created mappings from being applied.

Fallback: inline mappings

If mappingFilePath is not provided, you can pass the mappings directly as an inline array. This is useful when an LLM determines the mappings dynamically.

Data Directory

All auto-generated files are stored in .image-processor-mcp/ at the project root, organized into subdirectories:

| Path | Description | |------|-------------| | reports/scan-report-*.md | Compression report with summary, file tree, details, and comparison | | mappings/mappings-*.json | Old→new filename mappings, timestamp-paired with its report | | syncs/sync-report-*.md | Sync report (live run) with line-level details of all replacements | | syncs/dry-run/sync-report-*.md | Sync report from dry-run preview (no changes applied) |

Requirements

• Node.js 18 or higher
• NPM or compatible package manager

Environment Variables

• IMAGE_SEARCH_API_KEY: API key for keyword-based image search in download_image. Get a free key at https://www.pexels.com/api/key/

License

MIT License - see the LICENSE file for details.

Author

Dhvanil Pansuriya

GitHub | LinkedIn