roundcut-mcp

roundcut-mcp

为 AI Agent 提供本地图片工具，作为 MCP 服务。 在自己的设备上使用 sharp 对 JPG、PNG、WebP 和 AVIF 图片进行圆形裁剪、裁剪、调整大小、压缩和转换。不调用网络，不需要账户，也不上传文件：文件始终留在磁盘上。

由 RoundCut 制作。RoundCut 是一个免费的图片工具网站，支持 29 种语言。

安装

需要 Node 20 或更高版本。

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

配置方式相同：使用 stdio 服务，命令为 npx，参数为 -y roundcut-mcp。

Smithery

smithery.ai/servers/araluma/roundcut-mcp 会安装适用于 macOS（Apple Silicon）和 Windows（x64）的独立打包程序。在 Linux 或 Intel Mac 上，请使用上面的 npx。

工具

工具	功能	Agent 在以下情况调用
image_info	图片格式、尺寸、透明度、EXIF 方向。	用户询问图片信息，或在确定裁剪／调整大小的数值之前
circle_crop	圆形头像：居中裁成正方形，再应用圆形透明蒙版。size、format（默认 png）、用于 jpeg 的 background。	用户需要用于 Discord、Slack、LinkedIn、WhatsApp 或 GitHub 的圆形头像
crop_image	像素框（left、top、width、height），或居中裁剪为 1:1、4:5、16:9 等 aspect 比例。	用户需要裁出图片的一部分或固定比例（方形帖子、4:5 竖版照片、16:9 横幅）
resize_image	按 width、height 或 percent 调整大小。保持宽高比，除非设置 enlarge: true，否则绝不放大。使用 Lanczos3。	用户提供目标像素尺寸
compress_image	缩小文件，保持原格式。对 jpg/webp/avif 使用 quality（jpg 使用 mozjpeg），对 png 进行无损重新压缩。	文件需要变小（上传限制、加快页面加载），同时保持尺寸和格式
convert_image	转换为 jpeg、png、webp 或 avif。输入也可以是 GIF、TIFF 或 HEIC。保留透明度，或在转换为 jpeg 时平铺到 background 上。	用户需要转换成其他文件类型，例如将 iPhone HEIC 转为 JPG，或将 PNG 转为 WebP
roundcut_web_tools	提供指向此服务无法在本地运行的浏览器工具的链接：背景移除、AI 放大、批量转换、JPG 转 PDF。	用户询问其中一项功能时，而不是直接拒绝

每个工具都接收一个 input 路径，默认在其旁边写入结果 （photo.jpg 会生成 photo-circle.png、photo-resized.jpg、photo.webp），也可以写入 output。 结果包含文本摘要、指向文件的 resource_link、结构化 JSON （output、format、width、height、bytes、inputBytes）以及一张小尺寸 JPEG 预览图 （设置 preview: false 可跳过预览）。

示例：在已连接该服务的聊天客户端中：

将 ~/Pictures/me.jpg 制作成 512 px 的 WebP 圆形头像。

客户端会调用 circle_crop，参数为 { "input": "~/Pictures/me.jpg", "size": 512, "format": "webp" }， 并返回文件路径、尺寸和字节数。

限制

• 拒绝处理超过 80 百万像素的输入，以免意外调用分配数 GB 内存。
• 读取时会应用 EXIF 方向；输出方向正确，且不包含 EXIF。
• jpeg 不支持透明度：透明区域会平铺到 background 上（默认为白色）。

开发

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

src/engine.ts 是纯图片处理层（可直接测试）。src/index.ts 将其适配为 MCP 工具。

Smithery 发布：scripts/build-mcpb.sh 会根据 mcpb/manifest.json 构建 build/roundcut-mcp-<version>.mcpb（上限为 25 MB，因此只包含适用于 macOS arm64 和 Windows x64 的 sharp 二进制文件），然后 scripts/publish-smithery.sh 会上传该文件，并从构建好的服务中读取工具模式。

许可证

MIT。版权所有：Araluma。