Image Tools API

Image Tools Server

doc_processing_std_tools.image_tools

Image Tools MCP server.

Provides image manipulation capabilities (crop, resize, zoom, rotate, annotate, convert) using the Pillow library.

Fidelity guarantees:

• EXIF orientation is honoured on open (ImageOps.exif_transpose) so crops and zooms operate on the pixels the user actually sees.
• Saves preserve ICC profile / EXIF / DPI and re-encode JPEG/WebP at high quality (JPEG quality=95, subsampling=0). The output format is never changed implicitly — it follows the input extension or the caller's explicit output_path/format.
• A generous decompression-bomb cap protects against malicious inputs while still allowing legitimate high-DPI scans.
• Multi-frame inputs (animated GIF / multipage TIFF) are surfaced, not silently flattened — every tool takes an optional frame index.

image_annotate(path, annotations, output_path=None, frame=0)

Add annotations (text, rectangles, circles, arrows) to an image.

Parameters:

Name	Type	Description	Default
path	str	Path to the input image.	required
annotations	str	JSON list of annotation objects. Supported types: {"type": "rectangle", "x": int, "y": int, "width": int, "height": int, "color": str} {"type": "text", "x": int, "y": int, "text": str, "font_size": int, "color": str} {"type": "circle", "cx": int, "cy": int, "radius": int, "color": str} {"type": "arrow", "x1": int, "y1": int, "x2": int, "y2": int, "color": str}	required
output_path	str | None	Path for the output image (default: new file next to input, same format).	None
frame	int	Frame index for multi-frame inputs (default 0).	0

Returns:

Type	Description
str	Path to the annotated image.

image_convert(path, format, output_path=None, frame=0)

Convert an image between formats (PNG, JPEG, WEBP, BMP, TIFF).

Non-RGB/L modes are normalized to RGB for JPEG, compositing any alpha onto a white background (not black).

Parameters:

Name	Type	Description	Default
path	str	Path to the input image.	required
format	str	Target format — 'png', 'jpeg', 'webp', 'bmp', 'tiff'.	required
output_path	str | None	Path for the output image (default: new file with the new extension).	None
frame	int	Frame index for multi-frame inputs (default 0).	0

Returns:

Type	Description
str	Path to the converted image.

image_crop(path, left, top, right, bottom, output_path=None, frame=0)

Crop an image to specified coordinates.

Parameters:

Name	Type	Description	Default
path	str	Path to the input image.	required
left	int	Left coordinate of the crop box.	required
top	int	Top coordinate of the crop box.	required
right	int	Right coordinate of the crop box.	required
bottom	int	Bottom coordinate of the crop box.	required
output_path	str | None	Path for the output image (default: new file next to input, same format).	None
frame	int	Frame index for multi-frame inputs (default 0).	0

Returns:

Type	Description
str	Path to the cropped image.

image_get_info(path)

Get image dimensions, format, color mode, frame count, and file size.

Dimensions reflect the EXIF-corrected orientation (what a viewer shows), so they match the coordinate space the other tools operate in.

Parameters:

Name	Type	Description	Default
path	str	Path to the image file.	required

Returns:

Type	Description
str	JSON string with width, height, format, mode, n_frames, is_animated,
str	file_size_bytes, and file_size_human.

image_resize(path, width=None, height=None, output_path=None, frame=0)

Resize an image. Maintains aspect ratio if only one dimension is given.

Parameters:

Name	Type	Description	Default
path	str	Path to the input image.	required
width	int | None	Target width in pixels (optional).	None
height	int | None	Target height in pixels (optional).	None
output_path	str | None	Path for the output image (default: new file next to input, same format).	None
frame	int	Frame index for multi-frame inputs (default 0).	0

Returns:

Type	Description
str	Path to the resized image.

image_rotate(path, angle, output_path=None, frame=0)

Rotate an image by a given angle (counter-clockwise).

The canvas is expanded to fit the entire rotated image.

Parameters:

Name	Type	Description	Default
path	str	Path to the input image.	required
angle	float	Rotation angle in degrees (counter-clockwise).	required
output_path	str | None	Path for the output image (default: new file next to input, same format).	None
frame	int	Frame index for multi-frame inputs (default 0).	0

Returns:

Type	Description
str	Path to the rotated image.

image_zoom(path, region, zoom_factor=2.0, output_path=None, frame=0)

Zoom into a specific region of an image.

Crops the specified region, then scales it up by the zoom factor.

Parameters:

Name	Type	Description	Default
path	str	Path to the input image.	required
region	dict	Region to zoom as {"left": int, "top": int, "width": int, "height": int}.	required
zoom_factor	float	Zoom multiplier (default 2.0).	2.0
output_path	str | None	Path for the output image (default: new file next to input, same format).	None
frame	int	Frame index for multi-frame inputs (default 0).	0

Returns:

Type	Description
str	Path to the zoomed image.