Imagic MCP Server

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

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

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

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 l