Image Converter MCP Server

Professional MCP (Model Context Protocol) server for web-optimized image format conversion. Built with Sharp for high-performance image processing, focusing on SVG → WebP/PNG/JPEG conversions.

Features

• 🚀 High Performance: Built on Sharp (libvips) for fast image processing
• 🎨 SVG Support: Specialized SVG to raster conversion with scale options
• 📦 Batch Processing: Convert multiple images in one operation
• ⚙️ Quality Presets: Optimized defaults for web with customization options
• 🔍 Image Metadata: Get detailed info without conversion
• 🛡️ Type Safe: Full TypeScript with Zod validation

Installation

npm install
npm run build

Available Tools

1. convert_image - General Image Conversion

Convert any supported image to another format with quality and dimension options.

Parameters: | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | inputPath | string | ✅ | - | Absolute path to input image | | outputFormat | enum | ✅ | - | webp, png, or jpeg | | quality | number | ❌ | 80/85* | Quality (1-100) *varies by format | | width | number | ❌ | - | Target width (maintains aspect ratio) | | height | number | ❌ | - | Target height (maintains aspect ratio) | | outputPath | string | ❌ | auto | Output path (default: same dir, new ext) |

Example:

{
  "inputPath": "/path/to/image.png",
  "outputFormat": "webp",
  "quality": 85,
  "width": 1920
}

Response:

{
  "success": true,
  "outputPath": "/path/to/image.webp",
  "metadata": {
    "format": "webp",
    "width": 1920,
    "height": 1080,
    "size": 125430,
    "originalSize": 450230,
    "compressionRatio": "72.1%"
  }
}

2. convert_svg - SVG to Raster Conversion

Specialized tool for converting SVG files to raster formats with scaling options.

Parameters: | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | inputPath | string | ✅ | - | Absolute path to SVG file | | outputFormat | enum | ✅ | - | webp, png, or jpeg | | quality | number | ❌ | 80 | Quality (1-100) | | scale | number | ❌ | 1 | Scale factor (1x, 2x, 3x for retina) | | width | number | ❌ | - | Specific width (exclusive with scale) | | height | number | ❌ | - | Specific height (exclusive with scale) | | background | string | ❌ | transparent | Hex color or "transparent" |

Example (2x retina):

{
  "inputPath": "/path/to/logo.svg",
  "outputFormat": "webp",
  "scale": 2,
  "quality": 85
}

Example (specific dimensions):

{
  "inputPath": "/path/to/icon.svg",
  "outputFormat": "png",
  "width": 512,
  "height": 512,
  "background": "#ffffff"
}

3. batch_convert - Bulk Conversion

Convert multiple images in a directory in one operation.

Parameters: | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | inputDir | string | ✅ | - | Directory with source images | | outputFormat | enum | ✅ | - | webp, png, or jpeg | | pattern | string | ❌ | *.{svg,png,jpg,jpeg} | Glob pattern for file selection | | quality | number | ❌ | 80 | Quality (1-100) | | outputDir | string | ❌ | same | Output directory | | recursive | boolean | ❌ | false | Search subdirectories |

Example:

{
  "inputDir": "/path/to/images",
  "outputFormat": "webp",
  "pattern": "*.svg",
  "quality": 85
}

Response:

{
  "success": true,
  "results": [
    {
      "inputPath": "/path/to/images/logo.svg",
      "outputPath": "/path/to/images/logo.webp",
      "status": "success"
    }
  ],
  "summary": {
    "total": 10,
    "successful": 9,
    "failed": 1,
    "totalSizeBefore": 2450300,
    "totalSizeAfter": 890120
  }
}

4. get_image_info - Image Metadata

Get detailed information about an image without converting it.

Parameters: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | inputPath | string | ✅ | Absolute path to image file |

Example:

{
  "inputPath": "/path/to/image.png"
}

Response:

{
  "format": "png",
  "width": 1920,
  "height": 1080,
  "size": 450230,
  "hasAlpha": true,
  "colorSpace": "srgb",
  "orientation": 1
}

Quality Presets

Optimized defaults for web performance:

{
  webp: {
    quality: 80,      // Excellent quality/size balance
    effort: 4,        // Moderate compression effort
    lossless: false
  },
  jpeg: {
    quality: 85,      // High quality
    mozjpeg: true,    // Better compression
    progressive: true // Progressive loading
  },
  png: {
    compressionLevel: 9,  // Maximum compression
    progressive: false    // Lossless format
  }
}

Override quality: Pass quality parameter to customize (1-100).

Configuration for Claude Desktop

Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "image-converter": {
      "command": "node",
      "args": ["/absolute/path/to/image-converter-mcp/dist/index.js"],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

Development mode (using tsx):

{
  "mcpServers": {
    "image-converter": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/image-converter-mcp/src/index.ts"],
      "env": {
        "LOG_LEVEL": "debug"
      }
    }
  }
}

Use Cases

1. Convert SVG Logo to WebP (Standard & Retina)

// Standard
{
  "inputPath": "/assets/logo.svg",
  "outputFormat": "webp",
  "quality": 85
}

// 2x Retina
{
  "inputPath": "/assets/logo.svg",
  "outputFormat": "webp",
  "scale": 2,
  "quality": 85
}

2. Optimize All PNGs for Web

{
  "inputDir": "/assets/images",
  "outputFormat": "webp",
  "pattern": "*.png",
  "quality": 80
}

3. Create Responsive Image Sizes

// Desktop
{
  "inputPath": "/hero.jpg",
  "outputFormat": "webp",
  "width": 1920,
  "quality": 85
}

// Mobile
{
  "inputPath": "/hero.jpg",
  "outputFormat": "webp",
  "width": 768,
  "quality": 80
}

4. Convert SVG Icons to PNG with Background

{
  "inputPath": "/icon.svg",
  "outputFormat": "png",
  "width": 512,
  "height": 512,
  "background": "#ffffff"
}

Supported Formats

Input: SVG, PNG, JPG, JPEG, WebP, GIF, BMP, TIFF Output: WebP, PNG, JPEG

Error Handling

All errors are mapped to appropriate MCP error codes:

| Error Type | MCP Code | Example | |------------|----------|---------| | File not found | InvalidParams | File not found: /path/to/image.svg | | Invalid format | InvalidParams | Unsupported format: .txt | | Validation failed | InvalidParams | quality: Must be between 1 and 100 | | Permission denied | InternalError | Permission denied: /protected/file.png | | Conversion failed | InternalError | Conversion failed: Invalid SVG |

Logging

Logs are written to stderr in JSON format to avoid interfering with MCP stdio transport:

{
  "timestamp": "2025-01-25T10:30:45.123Z",
  "level": "info",
  "message": "Conversion completed",
  "meta": {
    "outputPath": "/path/to/output.webp",
    "compressionRatio": "72.1%"
  }
}

Log Levels: debug, info, warn, error Configure: Set LOG_LEVEL environment variable

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Development mode (auto-reload)
npm run dev

# Type checking
npx tsc --noEmit

Project Structure

image-converter-mcp/
├── src/
│   ├── index.ts                 # Server entry point
│   ├── tools/
│   │   └── index.ts             # MCP tool registration
│   ├── converters/
│   │   └── image-converter.ts   # Sharp conversion logic
│   ├── types/
│   │   └── index.ts             # TypeScript types & Zod schemas
│   └── utils/
│       ├── logger.ts            # Structured logging
│       ├── errors.ts            # Error handling
│       └── path-utils.ts        # Path utilities
├── dist/                        # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

Requirements

• Node.js: >= 18.0.0
• Sharp: Automatically installs platform-specific binaries
• OS: macOS, Linux, Windows (Sharp supported platforms)

License

MIT

Contributing

Contributions welcome! Please ensure:

• TypeScript strict mode compliance
• Zod schema validation for all inputs
• Error handling with appropriate MCP codes
• Tests for new features
• Documentation updates

Credits

Built with:

• Sharp - High-performance image processing
• MCP SDK - Model Context Protocol
• Zod - TypeScript-first schema validation