imageport

imageport

imageport does local image work with ImageMagick. It reads an image file's metadata — format, dimensions, color space, file size — resizes an image while preserving its aspect ratio, converts between the common web and print formats (png, jpg, webp, gif, avif, bmp, tiff), crops a rectangle out of an image, and rotates by an angle in degrees. Every operation is plain local file processing: there is no image generation, no hosted AI, and no network call anywhere in this package.

All five tools build ImageMagick argument arrays and run them through one injectable executor. The default executor spawns convert and identify with node:child_process execFile — argument arrays, never a shell string — so a host needs ImageMagick installed. When the binaries are absent, the spawn error (for example ENOENT) is surfaced as the tool error, honestly; nothing is faked. The unit tests exercise the same core through a fake executor that records the argument arrays, so they need no ImageMagick at all.

One behaviour worth knowing up front: ImageMagick decides the output format from the output file's extension, so convert_image replaces the requested output path's extension with the target format whenever the two differ (converting photo.png to webp writes photo.webp), and the result reports that effective path.

Install

npx -y @reneturcios/imageport mcp

Or run the container image (note: the container bundles no ImageMagick, so it passes MCP initialize / CLI usage smoke only — run on a host with ImageMagick installed for real work):

docker run -i ghcr.io/cloudcorprecords/imageport

CLI

imageport metadata <input>
imageport resize <input> <output> [--width n] [--height n]
imageport convert <input> <output> <format>
imageport crop <input> <output> <width> <height> <x> <y>
imageport rotate <input> <output> <angle>
imageport mcp
imageport --version

Examples:

imageport metadata photo.png
imageport resize photo.png photo-small.png --width 800
imageport convert photo.png photo-out.png webp   # writes photo-out.webp
imageport crop photo.png tile.png 200 200 40 60
imageport rotate photo.png photo-upright.png 90

Each command prints its result as JSON. Exit codes: 0 on success, 1 when ImageMagick fails (including when it is not installed), 2 for usage errors.

MCP server

One bin serves both faces. The mcp subcommand starts a stdio MCP server:

npx -y @reneturcios/imageport mcp

MCP client configuration:

{
  "mcpServers": {
    "imageport": {
      "command": "npx",
      "args": ["-y", "@reneturcios/imageport", "mcp"]
    }
  }
}

Tools

Tool	Input	What it does
get_image_metadata	input (required)	Reads format, width, height, color space, and file size via identify.
resize_image	input, output (required); width, height (at least one)	Resizes preserving aspect ratio via convert -resize.
convert_image	input, output, format (required)	Converts to png, jpg, webp, gif, avif, bmp, or tiff; the output extension is replaced with the format when it differs.
crop_image	input, output, width, height, x, y (required)	Crops a width x height region at offset x, y via convert -crop ... +repage.
rotate_image	input, output, angle (required)	Rotates by angle degrees via convert -rotate.

Development

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, fake executor, no ImageMagick needed
npm run dev     # run the CLI from source via tsx

License

MIT — see LICENSE.