Imagician

Imagician MCP is an MCP server that helps you resize, convert, crop, and compress images directly in your AI assistants like Claude Code and Cursor AI.

Instead of opening a separate application, you just tell your assistant what you need done, and Imagician executes the command locally.

Features

• 📏 Resize: Adjust image dimensions with several fit options like cover, contain, and fill.
• 🔄 Format Conversion: Switch between JPEG, PNG, WebP, and AVIF formats.
• ✂️ Crop: Cut out a specific region from an image by defining coordinates and size.
• 🗜️ Compress: Lower image file size with adjustable quality settings.
• ↩️ Rotate & Flip: Rotate an image by a specific angle or flip it horizontally or vertically.
• ⚡️ Batch Processing: Create multiple versions of an image at different sizes from a single source file.
• ℹ️ Metadata: Pull key information from an image file, such as its format, dimensions, and file size.

How To Use It

1. Install Imagician from npm or directly from the source code.

npm install -g @flowy11/imagician

If you prefer to build it yourself, clone the repository:

git clone https://github.com/flowy11/imagician.git
cd imagician
npm install
npm run build

2. Tell your AI assistant where to find the MCP server.

For Claude Code:
Edit your ~/.config/claude/config/settings/mcp-servers.json file and add this configuration:

{
  "imagician": {
    "command": "npx",
    "args": ["-y", "@flowy11/imagician"]
  }
}

For Cursor:
Add the following to your ~/.cursor/mcp_settings.json file:

{
  "mcpServers": {
    "imagician": {
      "command": "npx",
      "args": ["-y", "@flowy11/imagician"]
    }
  }
}

For Claude Desktop:
Modify your ~/Library/Application Support/Claude/claude_desktop_config.json file. The recommended setup uses npx, which pulls the latest version automatically.

{
  "mcpServers": {
    "imagician": {
      "command": "npx",
      "args": ["-y", "@flowy11/imagician"]
    }
  }
}

If you installed it globally, the command is simpler:

{
  "mcpServers": {
    "imagician": {
      "command": "imagician"
    }
  }
}

If you built it from source, you must point to the output file:

{
  "mcpServers": {
    "imagician": {
      "command": "node",
      "args": ["/path/to/imagician/dist/index.js"]
    }
  }
}

3. All built-in tools.

• resize_image: Resizes an image.
  • inputPath: The source image file.
  • outputPath: Where to save the new image.
  • width: Target width in pixels.
  • height: Target height in pixels.
  • fit: Method for resizing (e.g., cover, contain).
  • preserveAspectRatio: true by default to avoid distortion.
• convert_format: Changes an image’s file type.
  • inputPath: The source image file.
  • outputPath: Where to save the new image.
  • format: The target format (jpeg, png, webp, avif).
  • quality: A number from 1-100 for lossy formats.
• crop_image: Cuts a section out of an image.
  • inputPath: The source image file.
  • outputPath: Where to save the cropped image.
  • left: The starting pixel from the left edge.
  • top: The starting pixel from the top edge.
  • width: The width of the cropped area.
  • height: The height of the cropped area.
• compress_image: Reduces file size.
  • inputPath: The source image file.
  • outputPath: Where to save the compressed image.
  • quality: A number from 1-100.
  • progressive: Set to true for progressive JPEGs.
• rotate_image: Rotates an image.
  • inputPath: The source image file.
  • outputPath: Where to save the rotated image.
  • angle: The number of degrees to rotate.
  • background: The color for empty space created by the rotation.
• flip_image: Mirrors an image.
  • inputPath: The source image file.
  • outputPath: Where to save the flipped image.
  • direction: Choose horizontal, vertical, or both.
• get_image_info: Reads image metadata.
  • inputPath: The source image file.
• batch_resize: Creates multiple resized versions of an image.
  • inputPath: The source image file.
  • outputDir: The folder to save the new images.
  • sizes: An array defining the different sizes needed.
  • format: An optional output format for all generated images.

FAQs

Q: Do I need to have Node.js installed?
A: Yes, Imagician is a Node.js package. You will need a current version of Node.js and npm installed on your system to use it.

Q: What happens if I only specify a width for resizing, but not a height?
A: By default, the resize_image tool preserves the original aspect ratio. It will automatically calculate the corresponding height to prevent the image from looking stretched or squashed.

Q: Is my image data sent to a third-party server?
A: No. Imagician runs entirely on your local machine. All image processing happens locally, so your files are never uploaded anywhere.

Q: Can I combine multiple operations, like cropping and then resizing?
A: You perform operations one step at a time. Each tool call handles a single task. To combine operations, you would run one command and then use its output file as the input for the next command.