imagic-mcp
imagic-mcp is a local image processing MCP server that lets you manipulate images directly from AI assistants like Claude Desktop and Cursor — no uploads required, no internet needed.
Convert images: Transform between PNG, JPEG, GIF, WebP, and ICO formats, with optional quality control (1–100) for JPEG/WebP.
Resize images: Resize to custom pixel dimensions or named presets (e.g.,
favicon,instagram-square,full-hd,4k,youtube-thumbnail), with optional aspect ratio preservation.Convert and resize in one step: Combine format conversion and resizing into a single operation.
Merge multiple images: Combine 2+ images into one using horizontal, vertical, or grid layouts, with configurable gap size and background color.
Batch process a folder: Apply convert, resize, or convert-and-resize operations to all image files in a directory at once, with optional custom output folder — non-image files are automatically skipped.
All processing runs locally on your machine, so images never leave your device.
Provides specialized presets for converting and resizing images into standard Instagram formats, including square, portrait, and landscape dimensions.
Supports converting images to the JPEG format with adjustable quality settings for optimized file sizes.
Includes a built-in preset for resizing images to the standard YouTube thumbnail dimensions of 1280×720.
Imagic MCP Server
Convert, resize, and merge images directly from Claude Desktop, Cursor, and other MCP-compatible AI assistants — locally, with no uploads. Part of ImagicSave.
Requirements
Node.js 18 or later (includes npm)
Related MCP server: 🪄 ImageSorcery MCP
Installation
No clone needed. The package is distributed via npm. Configure your AI tool to run it with npx and it will be fetched automatically on first use.
Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"imagic": {
"command": "npx",
"args": ["-y", "imagic-mcp"]
}
}
}Restart Claude Desktop. The Imagic tools will appear automatically.
Cursor
Create or edit .cursor/mcp.json in your project (or ~/.cursor/mcp.json for global):
{
"mcpServers": {
"imagic": {
"command": "npx",
"args": ["-y", "imagic-mcp"]
}
}
}Usage Examples
Once configured, just ask your AI assistant:
"Convert
/tmp/photo.pngto WebP""Resize
/home/user/logo.pngto a favicon""Convert and resize
/tmp/banner.jpgto an Instagram square""Resize
/tmp/photo.jpgto 800×600, keep aspect ratio""Merge
/tmp/left.pngand/tmp/right.pngside by side and save to/tmp/merged.png""Stack these three images vertically with a 20px gap:
/tmp/a.jpg,/tmp/b.jpg,/tmp/c.jpg""Arrange
/tmp/img1.png,/tmp/img2.png,/tmp/img3.png,/tmp/img4.pngin a grid"
Tool Reference
Tool | Key Parameters | Description |
|
| Convert an image to a different format |
|
| Resize an image to custom dimensions or a named preset |
| All parameters from both tools above | Convert and resize in a single operation |
|
| Merge multiple images into one |
All parameters except input_path / input_paths and output_format / output_path are optional. Output for convert/resize defaults to the same directory as the input with a new extension.
merge_images details
Parameter | Type | Default | Description |
| string[] (min 2) | — | Ordered list of absolute image paths |
|
|
| How to arrange the images |
| integer ≥ 0 |
| Gap in pixels between images |
| hex string |
| Canvas/gap fill color |
| string | — | Absolute output path (format inferred from extension) |
Layouts:
horizontal — images placed side by side, centered vertically
vertical — images stacked top to bottom, centered horizontally
grid — auto columns (
ceil(√n)), each image centered in equal-size cells
Supported Formats
png, jpeg, gif, webp, ico
ICO encoding is built in — no extra dependencies required.
Presets
Preset Name | Dimensions |
| 1080 × 1080 |
| 1080 × 1350 |
| 1080 × 566 |
| 1200 × 675 |
| 1500 × 500 |
| 1920 × 1080 |
| 3840 × 2160 |
| 1280 × 720 |
| 32 × 32 |
Local Development & Testing
Use these steps to test the server from source before publishing to npm.
1. Install dependencies
cd mcp
npm install2. Smoke-test the server starts
node index.jsIt should block on stdin with no output — that's correct. Press Ctrl+C to exit.
3. Send a raw JSON-RPC call
Pipe a request directly to verify a tool works end-to-end:
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"convert_image","arguments":{"input_path":"/tmp/test.png","output_format":"webp"}}}' \
| node index.jsYou should see a JSON response with "success": true and the output path.
4. Point Claude Desktop or Cursor at the local source
Instead of npx, use node with an absolute path in your config:
Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"imagic": {
"command": "node",
"args": ["/absolute/path/to/imagic/mcp/index.js"]
}
}
}Cursor (.cursor/mcp.json):
{
"mcpServers": {
"imagic": {
"command": "node",
"args": ["/Users/pike6/work/project/website/imagic/mcp/index.js"]
}
}
}Restart Claude Desktop (or reload the Cursor window) after editing the config. Ask your AI assistant to convert or resize an image — it will call the local file directly.
5. Test with npm link (optional)
npm link makes the imagic-mcp binary available globally from your local source, which is the closest simulation to the published npx flow:
cd mcp
npm linkThen update your config to use imagic-mcp (same as the published form):
{ "command": "imagic-mcp", "args": [] }Run npm unlink -g imagic-mcp when you're done testing.
Privacy
Everything runs locally on your machine via stdio. Your images never leave your device and no internet connection is required for image processing.
For Repo Owners: Publishing to npm
Run once inside this directory after creating a free account at npmjs.com:
npm publishFor subsequent updates, bump the version field in package.json then run npm publish again.
Contributing
Contributions are welcome! Here's how to get started:
Fork the repository and create a branch from
mainInstall dependencies:
npm installMake your changes in
index.jsTest locally (see Local Development & Testing)
Open a pull request with a clear description of what you changed and why
Good areas to contribute:
New resize presets
Additional output formats
Performance improvements for large batches
Bug fixes
Please keep pull requests focused — one feature or fix per PR. For larger changes, open an issue first to discuss the approach.
License
MIT © ImagicSave
Available Tools
5 toolsconvert_and_resizeB
Convert an image to a new format and resize it in a single operation.
Inputs: input_path (required), output_format (required), quality, width, +4 more.
convert_imageC
Convert an image to a different format (PNG, JPEG, GIF, WebP, or ICO).
Inputs: input_path (required), output_format (required), quality, output_path.
merge_imagesC
Merge multiple images into a single image by arranging them horizontally, vertically, or in a grid.
Inputs: input_paths (required), output_path (required), layout, gap, +1 more.
process_folderB
Apply a convert, resize, or convert-and-resize operation to all image files in a folder. Non-image files are automatically skipped.
Inputs: folder_path (required), operation (required), output_format, quality, +5 more.
resize_imageA
Resize an image to custom dimensions or a named preset. Preserves the original format.
Inputs: input_path (required), width, height, preset, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
The tools have some clear distinctions but also notable overlap. Convert_and_resize and resize_image both handle resizing, while convert_and_resize and convert_image both handle format conversion, creating potential confusion about when to use each. However, the descriptions help clarify that convert_and_resize combines both operations, and process_folder is distinct as a batch processor.
All tool names follow a consistent snake_case pattern with clear verb_noun or verb_noun_noun structures (e.g., convert_and_resize, merge_images, process_folder). This predictability makes the set easy to scan and understand at a glance.
With 5 tools, this server is well-scoped for image processing tasks. Each tool serves a distinct purpose (conversion, resizing, merging, batch processing, and a combined operation), and the count feels appropriate without being overwhelming or insufficient for the domain.
The toolset covers core image operations well, including format conversion, resizing, merging, and batch processing. A minor gap is the lack of tools for more advanced manipulations like cropping, filtering, or metadata editing, but the provided tools support common workflows effectively.
Maintenance
Related MCP Connectors
Convert images to PNG, JPEG, WebP, or AVIF through one public remote MCP tool.
Image processing over MCP: compress and split images, generate images and QR codes.
Screenshots, PDFs, image editing, QR codes, email validation and more through one hosted MCP server.
Hosted MCP server for AI photo editing: nothing to install, no desktop photo editor needed.
Related MCP Servers
- AlicenseCqualityDmaintenanceMCP server for local compression of various image formats130 npm34MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server providing tools for image processing operations157 PyPI340PythonMIT
- FlicenseNot gradedqualityDmaintenanceA powerful Model Context Protocol (MCP) server for image processing, designed to empower AI models with advanced image manipulation capabilities.1-
- AlicenseAqualityDmaintenanceLocal image processing MCP server providing background removal, stock media search, resize, format conversion, and collage creation.5MIT