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)

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.png to WebP"
• "Resize /home/user/logo.png to a favicon"
• "Convert and resize /tmp/banner.jpg to an Instagram square"
• "Resize /tmp/photo.jpg to 800×600, keep aspect ratio"
• "Merge /tmp/left.png and /tmp/right.png side 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.png in a grid"

Tool Reference

Tool	Key Parameters	Description
convert_image	input_path, output_format, quality, output_path	Convert an image to a different format
resize_image	input_path, width, height, preset, lock_aspect_ratio, output_path	Resize an image to custom dimensions or a named preset
convert_and_resize	All parameters from both tools above	Convert and resize in a single operation
merge_images	input_paths, layout, gap, background, output_path	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
input_paths	string[] (min 2)	—	Ordered list of absolute image paths
layout	horizontal | vertical | grid	horizontal	How to arrange the images
gap	integer ≥ 0	0	Gap in pixels between images
background	hex string	#ffffff	Canvas/gap fill color
output_path	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
instagram-square	1080 × 1080
instagram-portrait	1080 × 1350
instagram-landscape	1080 × 566
twitter-post	1200 × 675
twitter-header	1500 × 500
full-hd	1920 × 1080
4k	3840 × 2160
youtube-thumbnail	1280 × 720
favicon	32 × 32

Local Development & Testing

Use these steps to test the server from source before publishing to npm.

1. Install dependencies

cd mcp
npm install

2. Smoke-test the server starts

node index.js

It 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.js

You 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 link

Then 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 publish

For subsequent updates, bump the version field in package.json then run npm publish again.

Contributing

Contributions are welcome! Here's how to get started:

1. Fork the repository and create a branch from main
2. Install dependencies: npm install
3. Make your changes in index.js
4. Test locally (see Local Development & Testing)
5. 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