Skip to main content
Glama

roundcut-mcp

Local image tools for AI agents, as an MCP server. Circle crop, crop, resize, compress and convert JPG, PNG, WebP and AVIF on your own machine with sharp. No network calls, no accounts, no upload: the files never leave the disk.

Made by RoundCut, the free image tools site (29 languages).

Install

Node 20 or newer.

npx roundcut-mcp

Claude Desktop / Claude Code

{
  "mcpServers": {
    "roundcut": { "command": "npx", "args": ["-y", "roundcut-mcp"] }
  }
}

Claude Code: claude mcp add roundcut -- npx -y roundcut-mcp

Cursor, Windsurf, VS Code

Same shape: a stdio server, command npx, args -y roundcut-mcp.

Related MCP server: mcp-image-tools

Tools

Tool

What it does

image_info

Format, dimensions, alpha, EXIF orientation.

circle_crop

Round profile picture: centered square plus a circular transparent mask. size, format (png default), background for jpeg.

crop_image

Pixel box (left, top, width, height) or a centered aspect such as 1:1, 4:5, 16:9.

resize_image

By width, height or percent. Keeps the aspect ratio, never enlarges unless enlarge: true. Lanczos3.

compress_image

Smaller file, same format. quality for jpg/webp/avif (mozjpeg for jpg), lossless recompression for png.

convert_image

To jpeg, png, webp or avif. Input may also be GIF, TIFF or HEIC. Transparency kept, or flattened onto background for jpeg.

roundcut_web_tools

Links to the browser tools this server does not run locally: background remover, AI upscaler, batch convert, JPG to PDF.

Every tool takes an input path and writes next to it by default (photo.jpg becomes photo-circle.png, photo-resized.jpg, photo.webp), or to output. Results carry a text summary, a resource_link to the file, structured JSON (output, format, width, height, bytes, inputBytes) and a small JPEG preview (preview: false to skip it).

Example, from a chat client with the server attached:

Make ~/Pictures/me.jpg a 512 px round avatar as WebP.

calls circle_crop with { "input": "~/Pictures/me.jpg", "size": 512, "format": "webp" } and answers with the file path, the dimensions and the byte count.

Limits

  • Inputs above 80 megapixels are refused, so a stray call cannot allocate gigabytes.

  • EXIF orientation is applied on read; the output is upright and carries no EXIF.

  • jpeg has no alpha: transparent areas are flattened onto background (white by default).

Develop

npm install
npm test        # builds, then node --test

src/engine.ts is the pure image layer (tested directly). src/index.ts adapts it to MCP tools.

License

MIT. Copyright Araluma.

Available Tools

7 tools
circle_cropCircle cropA

Make a round profile picture: center-square crop plus a circular transparent mask. png (default), webp and avif keep the transparent corners; jpeg flattens them onto a background color.

ParametersJSON Schema
NameRequiredDescriptionDefault
sizeNoOutput side in pixels (default: the largest centered square).
inputYes
formatNo
outputNoOutput file path. Default: next to the input, with a suffix and the right extension.
previewNoAttach a small JPEG preview to the result (default true).
qualityNoLossy quality 1-100 (default 80). Ignored for png.
backgroundNoCSS color used to flatten transparency when the output is jpeg (default #ffffff).

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the disclosure burden and does disclose non-obvious behavior: the center-square crop, transparent corners, and jpeg-specific background flattening. It could add detail about overwriting/output behavior, but the core behavioral traits are clearly stated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no filler: the first states the purpose and mechanism, the second covers the format-dependent edge cases. Every clause adds useful information and the most important detail is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter image transform with no output schema or annotations, the description plus schema covers the essential usage: what it does, how transparency is handled per format, and the default png behavior. It omits explicit when-not-to-use guidance and output/response shape, but these are either in the schema or not required for this straightforward operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 71%, and the description adds meaning beyond the schema for format and background: png is the default, transparency is preserved for png/webp/avif, and jpeg flattens against the background color. The input parameter is not explained, but its role is inferable and the key format semantics are supplied.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ('Make a round profile picture') and explains the mechanism ('center-square crop plus a circular transparent mask'). This clearly distinguishes it from generic crop_image or resize_image siblings and leaves no ambiguity about what the tool produces.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage context is implied by the phrase 'round profile picture', but the description never says when to prefer it over alternatives like crop_image, convert_image, or roundcut_web_tools, nor does it mention exclusions. An agent is left to infer selection criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

compress_imageCompress imageA

Smaller file, same format. jpg/webp/avif re-encode at quality (default 80, mozjpeg for jpg); png is recompressed losslessly.

ParametersJSON Schema
NameRequiredDescriptionDefault
inputYes
outputNoOutput file path. Default: next to the input, with a suffix and the right extension.
previewNoAttach a small JPEG preview to the result (default true).
qualityNoLossy quality 1-100 (default 80). Ignored for png.

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the behavioral disclosure burden. It reveals real operational behavior: lossy re-encoding at a quality level (with mozjpeg for jpg) versus lossless recompression for png. It does not mention overwrite behavior or the preview attachment side effect, but the core behavior is transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences carry all the essential information, with the main outcome front-loaded. There is no repeated schema content and every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a four-parameter tool with no output schema and no annotations, the description plus schema covers the key invocation needs: formats, quality semantics, output default, and preview. It lacks explicit safety/destructive context and a concrete statement of the input parameter's accepted form, but these are minor given the overall clarity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema documents output, preview, and quality, but the required input parameter has no schema description. The description adds meaningful format-dependent semantics to quality (default 80, mozjpeg for jpg, ignored for png), which is not present in the schema. It could further clarify what input accepts, but it partially compensates for the missing input description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description begins with a precise outcome ('Smaller file, same format') and specifies different behavior for jpg/webp/avif versus png. This makes the tool's purpose unmistakable and distinguishes it from siblings like convert_image, resize_image, and crop_image.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage context is implied: use it when you need a smaller file in the same format rather than converting, resizing, or cropping. However, there is no explicit when-to-use/when-not-to-use guidance and no named alternatives, so the agent must infer the boundary from sibling names.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

convert_imageConvert imageA

Convert between jpeg, png, webp and avif (the input may also be GIF, TIFF or HEIC). Transparency is kept except for jpeg, which is flattened onto background.

ParametersJSON Schema
NameRequiredDescriptionDefault
inputYes
formatYes
outputNoOutput file path. Default: next to the input, with a suffix and the right extension.
previewNoAttach a small JPEG preview to the result (default true).
qualityNoLossy quality 1-100 (default 80). Ignored for png.
backgroundNoCSS color used to flatten transparency when the output is jpeg (default #ffffff).

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It discloses an important behavioral detail beyond the schema: transparency is preserved except for JPEG, where it is flattened onto the `background` color. This is concrete and useful, though it does not mention side effects like file overwriting or permissions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no filler. The core conversion purpose is front-loaded, and the transparency caveat earns its place as a behavioral warning. Every word adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description plus schema covers the essential invocation details: input, output formats, optional output path, preview, quality, and background. The missing explicit sibling routing is a minor gap, but the tool is simple enough that an agent can invoke it correctly with the given information.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 67%, and the description adds meaning to the under-documented `input` parameter by listing accepted source formats (GIF, TIFF, HEIC). It also clarifies the `background` parameter's role in JPEG flattening, which goes beyond the schema's simple 'CSS color' description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('convert') and resource ('image'), and immediately lists the target formats: jpeg, png, webp, avif. This clearly distinguishes it from siblings like crop_image, resize_image, and compress_image, even without naming them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is for format conversion and adds accepted input formats (GIF, TIFF, HEIC), but it does not explicitly say when to use this tool over alternatives such as compress_image. There is no when-not or exclusion guidance, so the agent must infer the appropriate use case.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

crop_imageCrop imageB

Crop to a pixel box (left, top, width, height) or to a centered aspect ratio such as 1:1, 4:5 or 16:9.

ParametersJSON Schema
NameRequiredDescriptionDefault
topNo
leftNo
inputYes
widthNo
aspectNoCentered crop to this ratio, e.g. 16:9. Overrides the pixel box.
formatNo
heightNo
outputNoOutput file path. Default: next to the input, with a suffix and the right extension.
previewNoAttach a small JPEG preview to the result (default true).
qualityNoLossy quality 1-100 (default 80). Ignored for png.
backgroundNoCSS color used to flatten transparency when the output is jpeg (default #ffffff).

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden but only describes crop geometry. It does not disclose whether a new output file is created, whether the original is preserved, or that aspect overrides the pixel box (though the schema notes this). The use of 'or' leaves the interaction between the two modes ambiguous.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence with no wasted words. Every element—pixel box, centered aspect ratio, ratio examples—earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 11 parameters, no annotations, and no output schema, this description is too thin. It omits behavioral details such as output file creation, default format/quality effects, and how format/background interact with cropping. It is minimally adequate for crop geometry but incomplete for safe and correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaning to left/top/width/height by grouping them as a 'pixel box' and to aspect as a 'centered aspect ratio' with examples. With only 45% schema description coverage, this helps, but it does not compensate for undocumented parameters like format or input, nor clarify how aspect interacts with the pixel box.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Crop to a pixel box... or to a centered aspect ratio...') and clearly explains the two crop modes. It implicitly distinguishes itself from circle_crop by focusing on rectangular/pixel-box cropping, though it does not name any sibling tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The intended use is implied: choose this tool when a rectangular or aspect-ratio crop is needed. However, it gives no explicit guidance on when to prefer it over circle_crop, resize_image, or compress_image, leaving tool selection to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

image_infoImage infoA
Read-only

Read format, dimensions, alpha and EXIF orientation of an image file.

ParametersJSON Schema
NameRequiredDescriptionDefault
inputYesPath to a JPG, PNG, WebP, AVIF, GIF, TIFF or HEIC file.

TDQS

A4.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description aligns with the readOnlyHint annotation and adds the specific set of metadata that will be read. It does not go beyond the annotation to disclose additional behaviors such as error conditions, unsupported formats, or absence of side effects, but the annotation already covers the key safety aspect.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence states the operational verb and the exact data items returned with no filler or repetition. Every word contributes meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple, single-parameter read-only tool with no output schema, the description adequately enumerates the return contents. The input formats are fully covered by the schema, and sibling differentiation is clear from the contrasting verbs and tool names.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with the input parameter clearly documented as a path to supported image file types. The description adds value by indicating what will be read from that file, but it does not add new meaning about the parameter itself beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Read') with a clear resource ('an image file') and names the exact information returned: format, dimensions, alpha, and EXIF orientation. This clearly distinguishes it from the sibling manipulation tools such as crop_image, resize_image, and convert_image.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The read-only framing and the enumerated metadata fields make the inspection purpose clear, and all sibling tools are transformations, so an agent can infer when to select this tool. However, it stops short of explicitly stating when to use it versus alternatives, such as 'when you need metadata before modifying an image.'

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

resize_imageResize imageA

Resize by width, height or percent. Keeps the aspect ratio (fit=inside) and never enlarges unless enlarge=true. Lanczos3 resampling.

ParametersJSON Schema
NameRequiredDescriptionDefault
fitNo
inputYes
widthNo
formatNo
heightNo
outputNoOutput file path. Default: next to the input, with a suffix and the right extension.
enlargeNo
percentNo
previewNoAttach a small JPEG preview to the result (default true).
qualityNoLossy quality 1-100 (default 80). Ignored for png.
backgroundNoCSS color used to flatten transparency when the output is jpeg (default #ffffff).

TDQS

A3.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description carries the burden. It adds meaningful behavioral details: default fit=inside preserves aspect ratio, enlargement is disabled unless enlarge=true, and Lanczos3 resampling is used. It does not mention side effects like file writing, but core resizing behavior is well covered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with the core action, then key constraints and algorithm detail. Every sentence earns its place with no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 11 parameters, no annotations, and no output schema, the description covers the main resizing behavior but omits details like format defaults, input format expectations, and output path behavior beyond what the schema already says. Adequate for a common resize task, but with clear gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaning for parameters that the schema does not describe, such as width, height, percent, fit, and enlarge. However, schema coverage is only 36%, and the description leaves important parameters like input and format to be inferred, so compensation is partial.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: resizing an image by width, height, or percent, and it adds a key behavior (aspect-ratio preservation). It does not explicitly differentiate from sibling tools like crop_image or convert_image, but the verb and scope are unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The intended use case is implied: use this when you need to resize an image. However, there is no explicit guidance about when to prefer this over siblings such as convert_image, compress_image, or crop_image, and no exclusions are stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

roundcut_web_toolsRoundCut web toolsA
Read-only

Links to the RoundCut browser tools for what this server does not do locally: AI background removal, AI upscaling, batch conversion and image-to-PDF. Free, 29 languages.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The readOnlyHint annotation is supported and not contradicted. The description adds meaningful behavioral context: this tool is a link provider rather than a local processing operation, and it notes the service is free and supports 29 languages. It does not specify the exact format of the returned links, but for a read-only link tool this is sufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that front-loads the action and resource, followed by a compact list of use cases. The extra details 'Free, 29 languages' are brief and informative, and every element adds value without unnecessary fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only tool with no output schema, the description covers what the tool provides and why it exists. 'Links to...' implies the output is a set of links, but it could be slightly more explicit that the tool returns URLs/link references rather than performing the operations itself.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema is empty with zero parameters, so there are no parameter semantics to document in the description. The schema description coverage is 100% because there are no properties, so the baseline of 4 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a concrete action ('Links to...') and a resource ('RoundCut browser tools'), then enumerates specific capabilities: AI background removal, AI upscaling, batch conversion, and image-to-PDF. It distinguishes itself from sibling tools by stating these are things the server does not do locally, but it does not explicitly name a sibling alternative.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly states when to use this tool: when needing AI background removal, upscaling, batch conversion, or image-to-PDF conversion that the server does not handle locally. It implies the sibling tools are for local operations, but it does not explicitly say 'use sibling tools for local image operations.'

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 7 tool updatesv0.1.1
    • First observedcircle_crop
    • First observedcompress_image
    • First observedconvert_image
    • First observedcrop_image
    • First observedimage_info
    • First observedresize_image
    • First observedroundcut_web_tools

TDQS

A3.9/5.0

Scored across 7 tools

Disambiguation4/5

Each tool targets a distinct image operation, but compress_image and convert_image have some conceptual overlap since both involve re-encoding. The descriptions clarify that one keeps the format while the other changes it, so the ambiguity is mostly resolved. circle_crop is also distinct from crop_image because it adds a circular mask.

Naming Consistency4/5

Most tools follow a predictable verb_image pattern: compress_image, crop_image, resize_image, and convert_image. However, image_info is a noun phrase and roundcut_web_tools is a branded noun, which breaks the otherwise consistent convention.

Tool Count5/5

Seven tools is a well-scoped count for a local image-processing server: one inspection tool, five common transform tools, and one pointer to web-only features. No tool feels redundant, and the set is neither too thin nor bloated.

Completeness4/5

The tool surface covers core image workflows: inspect, compress, crop, circle-crop, resize, and convert. Minor gaps like rotate or flip are not covered, but the server explicitly points to web tools for advanced operations, so common local tasks do not hit dead ends.

Related MCP Connectors

Related MCP Servers