roundcut-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@roundcut-mcpCircle crop ~/Desktop/photo.jpg to 500px and save as png."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-mcpClaude 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 |
| Format, dimensions, alpha, EXIF orientation. |
| Round profile picture: centered square plus a circular transparent mask. |
| Pixel box ( |
| By |
| Smaller file, same format. |
| To |
| 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.jpga 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 --testsrc/engine.ts is the pure image layer (tested directly). src/index.ts adapts it to MCP tools.
License
MIT. Copyright Araluma.
Available Tools
7 toolscircle_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.
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | Output side in pixels (default: the largest centered square). | |
| input | Yes | ||
| format | No | ||
| output | No | Output file path. Default: next to the input, with a suffix and the right extension. | |
| preview | No | Attach a small JPEG preview to the result (default true). | |
| quality | No | Lossy quality 1-100 (default 80). Ignored for png. | |
| background | No | CSS color used to flatten transparency when the output is jpeg (default #ffffff). |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| input | Yes | ||
| output | No | Output file path. Default: next to the input, with a suffix and the right extension. | |
| preview | No | Attach a small JPEG preview to the result (default true). | |
| quality | No | Lossy quality 1-100 (default 80). Ignored for png. |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| input | Yes | ||
| format | Yes | ||
| output | No | Output file path. Default: next to the input, with a suffix and the right extension. | |
| preview | No | Attach a small JPEG preview to the result (default true). | |
| quality | No | Lossy quality 1-100 (default 80). Ignored for png. | |
| background | No | CSS color used to flatten transparency when the output is jpeg (default #ffffff). |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | ||
| left | No | ||
| input | Yes | ||
| width | No | ||
| aspect | No | Centered crop to this ratio, e.g. 16:9. Overrides the pixel box. | |
| format | No | ||
| height | No | ||
| output | No | Output file path. Default: next to the input, with a suffix and the right extension. | |
| preview | No | Attach a small JPEG preview to the result (default true). | |
| quality | No | Lossy quality 1-100 (default 80). Ignored for png. | |
| background | No | CSS color used to flatten transparency when the output is jpeg (default #ffffff). |
TDQS
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.
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.
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.
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.
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.
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 infoARead-only
Read format, dimensions, alpha and EXIF orientation of an image file.
| Name | Required | Description | Default |
|---|---|---|---|
| input | Yes | Path to a JPG, PNG, WebP, AVIF, GIF, TIFF or HEIC file. |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| fit | No | ||
| input | Yes | ||
| width | No | ||
| format | No | ||
| height | No | ||
| output | No | Output file path. Default: next to the input, with a suffix and the right extension. | |
| enlarge | No | ||
| percent | No | ||
| preview | No | Attach a small JPEG preview to the result (default true). | |
| quality | No | Lossy quality 1-100 (default 80). Ignored for png. | |
| background | No | CSS color used to flatten transparency when the output is jpeg (default #ffffff). |
TDQS
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.
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.
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.
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.
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.
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 toolsARead-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.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
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.
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.
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.
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.
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.
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.
7 tool updates
v0.1.1- First observed
circle_crop - First observed
compress_image - First observed
convert_image - First observed
crop_image - First observed
image_info - First observed
resize_image - First observed
roundcut_web_tools
TDQS
Scored across 7 tools
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.
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.
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.
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
Image processing for AI agents: resize, convert, compress, crop, and web-ready AI-generated images.
Video, audio, and image processing for AI agents: convert, transcribe, upscale - 150+ operations.
Resize, convert, compress, crop, thumbnail and watermark images from your AI chat.
PDF, image, video, OCR, screenshot, SQL, QR and text tools for agents. No API key, no signup.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceProvides AI agents with tools to convert images between formats and inspect image metadata, enabling seamless image processing within agent workflows.113MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to perform image processing tasks such as sprite sheet splitting, resizing, cropping, and batch operations on local images.MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to locally process images with tools for cropping, zooming, enhancement, edge detection, segmentation, and text region extraction, all without external API keys. It uses PIL, OpenCV, and scikit-image for robust image analysis.MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to perform GIMP-style image operations such as open, resize, crop, flip, rotate, blur, desaturate, text overlay, export, and batch processing via MCP tools, supporting both mock (Pillow) and live GIMP backends.1MIT