@javascribe/image-toolbox

MCP Server for image processing — 让 AI Agent 在本地完成图片压缩、缩放、格式转换和批量处理。

基于 sharp (libvips)，所有处理在用户本地执行，零服务器消耗、零网络上传。

快速接入

在你的 AI 客户端（Claude Desktop / Cursor / Qoder 等）中添加：

{
  "mcpServers": {
    "image-toolbox": {
      "command": "npx",
      "args": ["@javascribe/image-toolbox"]
    }
  }
}

配置完成后，Agent 自动发现以下 6 个工具，无需额外代码。

工具清单

get_image_info

获取图片详细信息（格式、尺寸、文件大小、色彩空间等）。

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | input | string | ✅ | 图片文件路径 |

compress_image

按质量压缩图片。

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | input | string | ✅ | 输入文件路径 | | output | string | ✅ | 输出文件路径 | | quality | number | ❌ | 压缩质量 1-100，默认 75 | | format | string | ❌ | 输出格式：jpeg/png/webp/avif/gif/tiff |

resize_image

缩放图片，支持按像素或百分比。

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | input | string | ✅ | 输入文件路径 | | output | string | ✅ | 输出文件路径 | | width | number | ❌ | 目标宽度 (px) | | height | number | ❌ | 目标高度 (px) | | percentage | number | ❌ | 缩放百分比 1-100 | | fit | string | ❌ | 适配模式：cover/contain/fill/inside/outside | | format | string | ❌ | 输出格式 | | quality | number | ❌ | 输出质量 1-100 |

convert_format

转换图片格式。

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | input | string | ✅ | 输入文件路径 | | output | string | ✅ | 输出文件路径 | | format | string | ✅ | 目标格式：jpeg/png/webp/avif/gif/tiff | | quality | number | ❌ | 输出质量 1-100 |

compress_to_size

将图片压缩到指定目标大小（KB），保持长宽尺寸不变。自动搜索最优压缩参数，必要时降低细节。

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | input | string | ✅ | 输入文件路径 | | output | string | ✅ | 输出文件路径 | | target_size | number | ✅ | 目标大小 (KB) | | format | string | ❌ | 输出格式 |

batch_compress

批量压缩图片，支持 glob 模式匹配。可按质量压缩，或统一压缩到指定目标大小。

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | input_pattern | string | ✅ | glob 模式或目录路径，如 ./photos/*.jpg | | output_dir | string | ✅ | 输出目录 | | target_size | number | ❌ | 目标大小 (KB)，指定后每张图压缩到该大小以内，保持尺寸不变 | | quality | number | ❌ | 压缩质量 1-100，默认 75（未指定 target_size 时生效） | | format | string | ❌ | 输出格式 | | percentage | number | ❌ | 缩放百分比（未指定 target_size 时生效） |

使用示例

配置完成后，直接用自然语言指挥 Agent：

"把 ./photos 目录下的所有图片压缩到 200KB 以内"
"将 logo.png 转成 WebP 格式，质量 80"
"把这张 4000x3000 的照片缩小到 50%"
"批量压缩 ./images/*.jpg，质量 60，输出到 ./output"

支持格式

• 输入：JPEG, PNG, WebP, AVIF, GIF, TIFF, BMP, SVG, HEIC
• 输出：JPEG, PNG, WebP, AVIF, GIF, TIFF

环境要求

• Node.js >= 18
• 首次运行 npx 会自动下载 sharp 的平台原生二进制（约 10MB）

隐私说明

所有图片处理完全在本地完成，不会上传到任何服务器。

License

MIT