MCP Image Compressor

基于 @modelcontextprotocol/sdk 实现的图片压缩 MCP Server。

功能特性

• 压缩图片文件（JPEG、PNG、WebP 格式）
• 支持压缩 http/https 线上图片地址
• 批量压缩整个文件夹中的图片
• 可调节输出质量（1-100）
• 支持按最大宽度/高度等比缩放
• 支持限制最大文件大小
• 支持格式转换
• 支持递归子目录、输入格式过滤和保留目录结构输出
• 支持域名白名单、下载超时/重试和临时文件自动清理

环境要求

• Node.js >= 18.0.0
• npm >= 9.0.0

安装

npm install

构建

npm run build

使用方式

作为 MCP Server 运行

npm start

在 Cursor 中使用（npx 方式）

1. 在 Cursor 设置中添加 MCP Server：

   • 打开 Cursor 设置 → Features → MCP
   • 点击 "Add New MCP Server"

2. 配置 server：

   {
     "mcpServers": {
       "image-compressor": {
         "command": "npx",
         "args": ["-y", "@bangdao-ai/mcp-image-compressor"]
       }
     }
   }

3. 重启 Cursor 后，在 AI 对话框中即可使用图片压缩功能

在 Cursor 中使用（本地开发方式）

{
  "mcpServers": {
    "image-compressor": {
      "command": "node",
      "args": ["/path/to/mcp/dist/index.js"]
    }
  }
}

工具参数

compress-image

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | inputPath | string | 否 | - | 输入图片的绝对路径，与 inputUrl 二选一 | | inputUrl | string | 否 | - | 输入图片的 http/https 地址，与 inputPath 二选一 | | outputPath | string | 是 | - | 输出图片的绝对路径 | | quality | number | 否 | 80 | 输出质量 (1-100) | | maxWidth | number | 否 | - | 最大宽度（正整数，保持宽高比） | | maxHeight | number | 否 | - | 最大高度（正整数，保持宽高比） | | maxSize | number | 否 | - | 最大文件大小（MB，正数），如 0.5 表示 500KB | | format | string | 否 | jpeg | 输出格式：jpeg, png, webp | | preserveInputFormat | boolean | 否 | false | 是否保留原始图片格式并据此校验输出扩展名 | | avoidLargerThanInput | boolean | 否 | true | 是否尽量避免输出文件大于原图 | | sizeStrategy | string | 否 | balanced | 体积策略：strict 优先体积，balanced 优先画质 | | allowOverwrite | boolean | 否 | false | 是否允许覆盖已存在输出文件 | | allowedDomains | string[] | 否 | - | 远程地址白名单域名，支持主域名及其子域名；传 ["*"] 表示不限制 | | timeoutMs | number | 否 | 10000 | 远程下载超时时间（毫秒） | | retryCount | number | 否 | 1 | 远程下载失败后的重试次数 | | maxDownloadBytes | number | 否 | 26214400 | 远程下载大小上限（字节，默认 25MB） | | allowedRoot | string | 否 | - | 安全根目录，设置后输入/输出必须在该目录内；传 "*" 表示不限制 |

说明：inputPath 与 inputUrl 必须二选一。 说明：本地输入时 inputPath 与 outputPath 必须是绝对路径，且不能相同。 说明：outputPath 扩展名必须与 format 一致（例如 format=png 时输出需为 .png）。 说明：当 preserveInputFormat=true 时，会优先使用原图格式，并按原格式校验 outputPath 扩展名。 说明：远程地址仅支持 http/https，下载完成后会自动清理临时文件。 说明：远程下载会逐跳校验重定向目标是否仍在 allowedDomains 白名单中。 说明：当 allowedDomains=["*"] 时，表示关闭域名白名单限制。 说明：远程下载默认限制为 25MB，可通过 maxDownloadBytes 调整。 说明：当 allowedRoot="*" 时，表示关闭路径根目录限制。 PNG 说明：balanced 策略默认优先画质；strict 策略会启用更激进的 PNG 量化以优先体积。

compress-folder

| 参数 | 类型 | 必填 | 默认值 | 说明 | |------|------|------|--------|------| | inputDir | string | 是 | - | 输入目录的绝对路径 | | outputDir | string | 是 | - | 输出目录的绝对路径 | | recursive | boolean | 否 | false | 是否递归处理子目录 | | inputFormats | string[] | 否 | 全部支持格式 | 仅处理这些输入格式：jpeg、png、webp | | quality | number | 否 | 80 | 输出质量 (1-100) | | maxWidth | number | 否 | - | 最大宽度（正整数，保持宽高比） | | maxHeight | number | 否 | - | 最大高度（正整数，保持宽高比） | | maxSize | number | 否 | - | 最大文件大小（MB，正数），如 0.5 表示 500KB | | format | string | 否 | jpeg | 输出格式：jpeg, png, webp | | preserveInputFormat | boolean | 否 | false | 是否保留原始图片格式并保留对应输出扩展名 | | avoidLargerThanInput | boolean | 否 | true | 是否尽量避免输出文件大于原图 | | sizeStrategy | string | 否 | balanced | 体积策略：strict 优先体积，balanced 优先画质 | | allowOverwrite | boolean | 否 | false | 是否允许覆盖已存在输出文件 | | skipExisting | boolean | 否 | false | 输出文件已存在时是否跳过 | | allowedRoot | string | 否 | - | 安全根目录，设置后输入/输出都必须位于该目录内；传 "*" 表示不限制 |

说明：inputDir 与 outputDir 必须是绝对路径，且不能相同。 说明：输出会保留输入目录结构，并根据 format 自动生成目标扩展名。 说明：当 preserveInputFormat=true 时，会按每张原图格式输出，对应扩展名也会随之保留。 说明：当 allowOverwrite=false 且 skipExisting=true 时，已存在的输出文件会被跳过并记录在批量结果中。 说明：当 allowedRoot="*" 时，表示关闭路径根目录限制。

测试

npm test

返回结果示例

{
  "success": true,
  "message": "图片压缩成功",
  "input": {
    "path": "/path/to/input.jpg",
    "format": "jpeg",
    "size": 2846064,
    "width": 4214,
    "height": 2846
  },
  "output": {
    "path": "/path/to/output.jpg",
    "format": "jpeg",
    "size": 407707,
    "width": 4214,
    "height": 2846,
    "quality": 12
  },
  "compressionRatio": "85.67%"
}

发布到 npm

# 交互式发版，可选择是否执行 npm login 和 npm publish --access public
npm run release

# 非交互式 patch 发版，并发布到 npm
npm run release -- patch --publish

# 非交互式 patch 发版，先登录 npm，再发布到 npm
npm run release -- patch --npm-login --publish

说明：

• npm run release 会创建 release commit 和 Git tag。
• 传 --publish 时，脚本会先执行 npm run build，再执行 npm publish --access public。
• 传 --npm-login 时，脚本会在发布流程中执行 npm login。
• 支持的发版类型参数为 patch、minor、major。

依赖

• @modelcontextprotocol/sdk - MCP 协议 SDK
• sharp - 高性能图片处理库
• zod - TypeScript 模式验证