@image-converter/mcp

An MCP (Model Context Protocol) server for converting images to AVIF and WebP formats using ImageMagick. Optimizes images for better web performance with support for batch conversion, quality control, and more.

Prerequisites

ImageMagick Installation

This package requires ImageMagick to be installed on your system.

Windows:

• Download from https://imagemagick.org/script/download.php
• Install and ensure magick command is in your PATH

macOS:

brew install imagemagick

Linux (Ubuntu/Debian):

sudo apt-get install imagemagick

Verify Installation:

magick -version

Installation

MCP Configuration

Add to your MCP configuration file:

For Claude Code (.claude.json):

{
  "mcpServers": {
    "image-converter": {
      "command": "node",
      "args": ["path/to/node_modules/@image-converter/mcp/src/index.js"]
    }
  }
}

For OpenCode (opencode.json):

{
  "mcp": {
    "image-converter": {
      "type": "local",
      "command": ["node", "path/to/node_modules/@image-converter/mcp/src/index.js"],
      "enabled": true
    }
  }
}

For Other MCP Clients:

# Install globally
npm install -g @image-converter/mcp

# Or use npx
npx @image-converter/mcp

Available Tools

convert_image

Convert a single image to AVIF or WebP format.

Parameters: | Parameter | Type | Required | Default | Description | |-----------------|---------|----------|---------|--------------------------------------| | inputPath | string | Yes | - | Path to input image | | outputFormat | string | Yes | - | Output format: "avif" or "webp" | | outputPath | string | No | auto | Custom output path | | quality | number | No | 75 | Quality 1-100 | | critical | boolean | No | false | If true, applies 25% quality drop |

Example:

convert_image({
  inputPath: "logo.png",
  outputFormat: "avif",
  quality: 75
})

convert_folder

Batch convert all images in a folder to AVIF or WebP format.

Parameters: | Parameter | Type | Required | Default | Description | |-----------------|----------|----------|---------|-----------------------------------| | inputFolder | string | Yes | - | Path to input folder | | outputFolder | string | No | same | Output folder path | | outputFormat | string | Yes | - | Output format: "avif" or "webp" | | quality | number | No | 75 | Quality 1-100 | | critical | boolean | No | false | If true, applies 25% quality drop | | recursive | boolean | No | false | Include subfolders | | skipExisting | boolean | No | true | Skip if output exists |

Example:

convert_folder({
  inputFolder: "./images",
  outputFormat: "avif",
  quality: 80,
  recursive: false,
  skipExisting: true
})

get_image_info

Get information about an image.

Parameters: | Parameter | Type | Required | Description | |-----------|---------|----------|--------------------| | path | string | Yes | Path to image file |

Example:

get_image_info({ path: "photo.jpg" })

list_images

List all images in a folder.

Parameters: | Parameter | Type | Required | Default | Description | |-------------|---------|----------|---------|----------------------------------------| | folder | string | Yes | - | Path to folder | | recursive | boolean | No | false | Include subfolders | | formats | array | No | all | Filter by formats, e.g. ["png", "jpg"] |

Example:

list_images({
  folder: "./assets",
  formats: ["png", "jpg", "webp"]
})

Usage Examples

Convert Single Image

User: "Convert logo.png to AVIF"
Agent calls: convert_image({ inputPath: "logo.png", outputFormat: "avif" })
Result: Creates logo.avif alongside logo.png

Batch Convert Folder

User: "Optimize all images in /assets to AVIF at quality 80"
Agent calls: convert_folder({ 
  inputFolder: "/assets", 
  outputFormat: "avif", 
  quality: 80 
})
Result: Creates .avif files for all supported images in /assets

Critical Mode (Maximum Compression)

User: "Convert image.jpg to AVIF with maximum compression"
Agent calls: convert_image({ 
  inputPath: "image.jpg", 
  outputFormat: "avif", 
  critical: true 
})
Result: Applies 75% of the quality setting (default 75 = ~56 effective)

Supported Formats

Input:

• PNG, JPG/JPEG, WebP, GIF, BMP, TIFF

Output:

• AVIF (default recommended)
• WebP

Why AVIF?

AVIF offers significant advantages over traditional formats:

• 50-70% smaller file sizes compared to JPEG/PNG
• Better quality than WebP at similar file sizes
• Supported by all modern browsers
• Lossy & lossless compression options

Technology

This MCP server uses:

• ImageMagick - Image processing
• @modelcontextprotocol/sdk - MCP implementation

License

MIT License - see LICENSE file.

Author

Pratham Bindal

Contributing

Contributions welcome! Please open an issue or submit a PR.