Skip to main content
Glama

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.

imagic-mcp MCP server

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

Available Tools

5 tools
convert_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

    A3.5/5.0

    Scored across 5 tools

    Disambiguation3/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers