thumbnails

mcp-image

说一句“把这五张照片调整到 1200 像素宽”，或“缩小这张截图并去掉其中的 GPS 信息”，一秒钟内就能在你的机器上完成。这个 MCP 服务可处理那些通常会让你打开网页上传工具的小型图像任务：调整大小、在 PNG、JPEG、BMP、GIF 和 TIFF 之间转换、压缩并显示实际压缩前后的字节数、裁剪、为文件夹生成缩略图、添加带有你企业名称的水印，以及移除手机相机写入每张照片的 EXIF 信息块。无需上传、无需账户、无需原生依赖，也无需图像编辑器。

已收录于 官方 MCP Registry（io.github.theluckystrike/image-resize-convert-compress-watermark）。

已收录于 AI Product Index - 提供可用的远程端点 mcp.zovo.one/s/image，有免费套餐，无需注册。

自由职业者日常经营中的图像杂务，现在可以在聊天中完成，而不用打开你不太愿意把客户照片交给它的浏览器标签页。

60 秒安装

@theluckystrike/mcp-image 尚待发布到 npm。在此之前，可使用一键安装包 .mcpb，或克隆并构建；以下两种方式均已验证。

一键安装（.mcpb）：从最新版本下载 image.mcpb，然后在 Claude Desktop 中双击： https://github.com/theluckystrike/mcp-servers/releases/latest

（claude_desktop_config.json）：

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

Claude Code：

claude mcp add image -- npx -y @theluckystrike/mcp-image

（.cursor/mcp.json）：

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

上述 npx 方式将在软件包发布后立即可用。在此之前，请使用上面的 .mcpb 安装包，或通过以下三个命令从源代码构建：

git clone https://github.com/theluckystrike/mcp-servers.git && cd mcp-servers
npm install
npm run build -w packages/mcp-license -w servers/image

然后将客户端的 command 指向 node，并传入一个参数：servers/image/dist/index.js 的绝对路径。

要以 Pro 模式运行，请在同一个配置块中设置 MCP_LICENSE_KEY，或使用你的密钥调用一次 license_activate。

工具

工具	功能
image_info	格式、像素尺寸、百万像素数、宽高比、文件字节数、图像是否带有 Alpha 通道，以及每像素占用的字节数
image_resize	调整尺寸后的副本。inside 在框内适配并保持宽高比，cover 填满框并裁掉溢出部分，exact 拉伸图像。指定宽度或高度之一，另一项会按比例调整
image_convert	重新编码为 PNG、JPEG、BMP、GIF 或 TIFF。转换为 JPEG 时，透明部分会铺上白色，并在结果中说明
image_compress	减小文件字节数，并报告压缩前后的数量和节省的百分比。可设置 quality（默认值为 80）、max_width 和 max_bytes，一次调用即可达到目标大小
image_crop	裁剪矩形区域：x、y 从左上角开始计算，另有 width、height。如果矩形超出边缘，则会拒绝操作并返回实际尺寸，不会自动调整范围
image_thumbnails	为每个文件生成一张缩略图并放入 out_dir，每张缩略图都适配在 size × size 范围内并保持宽高比
image_watermark	在图像角落叠加文字，并设置不透明度；文字为白色，底板为半透明。不提供文字时，使用共享配置文件中的企业名称：mcp-invoice 和 mcp-docx
image_strip_metadata	仅保留像素的副本：不会保留 EXIF、GPS、相机信息、拍摄时间、XMP 和色彩配置文件
image_batch_resize	调整整批文件的尺寸并放入 out_dir，每个文件都保持自身的宽高比，命名格式为 <name>-<W>x<H>.<ext>
image_dominant_colors	图像中占比最高的颜色，以十六进制代码及其覆盖的像素比例表示。免费版：3 种；Pro：最多 16 种
license_status	显示免费版或 Pro 模式
license_activate	激活 Pro 密钥（离线验证）

资源：image://recent 返回最近 25 次操作，按时间从新到旧排列，并包含输入、写入的文件及操作时间。 提示词：prepare_for_web 会将相机尺寸的图像缩小为网页尺寸的 JPEG，删除随图像附带的元数据，并报告节省的字节数。

你可以这样说

你说	工具
“这张图有多大？有没有透明部分？”	image_info
“把这张图的宽度改为 1200 像素。”	image_resize
“把这个 PNG 转成 JPEG。”	image_convert
“这张照片有 8 MB，压到 1 MB 以下。”	image_compress
“把这张截图顶部的横幅裁掉。”	image_crop
“为这个文件夹里的所有内容生成缩略图。”	image_thumbnails
“把我的公司名称加在这张照片的角落。”	image_watermark
“发送之前去掉 GPS 坐标。”	image_strip_metadata
“把这些图的宽度都调整为 1600 像素。”	image_batch_resize
“这个徽标由哪些颜色组成？”	image_dominant_colors
“把这张图处理成适合网站使用的样子。”	prepare_for_web 提示词

示例

You: This photo is too big for the site. Get it to 1600 wide and drop the metadata.

  image_info { path: "~/photos/DSC_0491.jpg" }
  -> 6000x4000, 24 MP, JPEG, 8.4 MB, no alpha

  image_compress {
    path: "~/photos/DSC_0491.jpg",
    max_width: 1600,
    quality: 80,
    max_bytes: 256000,
    out_path: "~/photos/DSC_0491-web.jpg"
  }
  -> 8.4 MB -> 243.7 KB (8809124 -> 249556 bytes, -97.2%)
  -> Method: JPEG quality 62 (searched down from 80 in 5 encodes to fit 250.0 KB)
     and a resize to 1600 px wide
  -> ~/photos/DSC_0491-web.jpg, 1600x1067, JPEG

重新编码为 JPEG 时，也会删除相机写入的 EXIF 数据块，包括 GPS 坐标。原始文件保持逐字节不变。

免费版与 Pro

	免费版	Pro
image_info	不限次数，尺寸不限	不限次数
image_resize、image_convert、image_compress、image_crop	源文件不限，写入的输出最大为 4 MP（2000x2000 左右）	尺寸不限，但受 50 MB / 10,000 px 的输入上限限制
image_strip_metadata	尺寸不限	尺寸不限
image_thumbnails、image_batch_resize	每次最多 5 个文件，每个输出最大为 4 MP	文件数量和尺寸不限
image_watermark	使用共享配置文件中的企业名称	可使用任意传入的文字
image_dominant_colors	前 3 种颜色	最多 16 种

免费版限制针对的是写入的内容，而非读取的内容：将 12 MP 的手机照片缩小到 1600 px 宽是免费操作，因为这正是要完成的任务。再次写入 12 MP 图像则需要 Pro。

达到套餐限制时会返回说明，而不是报错；拒绝调用时不会写入任何内容。

Pro 为一次性付费：单个服务 $19，或为集合中的每个服务支付 $39，可终身使用。

quality 是 JPEG 参数，而且仅适用于 JPEG

这是图像压缩中最让人意外的一点，因此服务会在自己的回答中说明，而不是接受一个数字后悄悄不做任何处理。JPEG 会丢弃细节以缩小文件，quality 就是控制丢弃程度的旋钮。PNG 是无损格式：没有这个旋钮。给 PNG 输出传入 quality: 40 不会让 PNG 缩小 60%，而是得到完全相同的 PNG。

因此，输出格式由 out_path 的扩展名决定，这就是可调节的选项：

• out_path: "shot-small.jpg"，quality 会生效，照片通常会缩小 80-95%。
• out_path: "shot-small.png"，系统会报告 quality 不适用，只有 max_width 能减少字节数。

曾测试过将调色板量化作为 PNG 的替代方案，但最终弃用：通过 16 色量化器重新编码一张 300x220 的噪点 PNG 后，文件反而变大了（115,451 字节，而非 39,262），因为这里的编码器无论如何都会写入 RGBA，而量化只会破坏 deflate 步骤原本利用的行间相似性。声称能压缩却返回更大文件的工具，不如明确说明哪些旋钮可用的工具。

因此，image_compress 始终会报告压缩前后的字节数、百分比和实际使用的方法；如果输出文件变大，也会说明这一点，并建议保留原文件。

从文件头检测并拒绝解压炸弹，不进行任何解码

一个 4 KB 的 PNG 可以声明其尺寸为 20,000 x 20,000 像素。解码它会分配 1.6 GB 的 RGBA 内存，并在解码后编写的任何大小检查有机会运行之前就使进程崩溃。因此，系统会从容器文件头读取声明尺寸：PNG IHDR、JPEG SOF 段、GIF 逻辑屏幕描述符、BMP 信息头、首个 TIFF IFD；如果文件任一边超过 10,000 px，就会在此处拒绝，并在消息中说明所需内存：

Error: /path/bomb.png declares 20000x20000 pixels in its PNG header and was refused before decoding:
this server caps a side at 10000 px. A small file that declares an enormous canvas is a decompression
bomb - decoding it would allocate 1526 MB of RGBA. Nothing was decoded.

之后还会再次检查解码后的尺寸，因为在特殊 TIFF 文件中，文件头探测可能返回空结果；只在某些情况下运行的防护不算防护。

绝不覆盖现有文件，也绝不修改输入文件

每个工具都会写入新文件，并保持输入文件逐字节不变；这是有意设计的，不提供原地修改模式。若 out_path 已存在，则会拒绝操作：

Error: /path/shot-small.png already exists and nothing was written.
Pass overwrite: true to replace it, or give a different out_path.

系统会通过独占创建保留路径，而不是先检查路径是否存在，因此两个进程同时写入同一个 out_path 时，不会相互覆盖：一个进程成功，另一个会被拒绝且不会写入任何内容。image_thumbnails 和 image_batch_resize 会在写入任何文件前保留所有输出路径，因此即使文件 3 发生冲突，也不会留下只完成一半的批处理文件 1 和 2；此外，保留会被释放，因此磁盘上也不会留下空文件。

如果你确实想替换文件，请传入 overwrite: true。

overwrite: true 仍不允许输出文件同时作为输入文件。将结果写回某个源文件会破坏该源文件：像素已在内存中解码，随后又被写回其来源文件，因此一张 4000 px 的原图会变成 512 px 的缩略图，之后每次读取该路径时都会悄悄得到错误结果。因此，如果 out_path 解析后与本次调用的任何输入路径相同，或与其共享 inode，系统会在开始任何处理前拒绝操作。 ##“strip metadata” 实际所做的事

image_strip_metadata 会解码图像，并根据原始像素重新编码。EXIF、GPS 坐标、相机和镜头信息、拍摄时间、XMP 数据包以及嵌入的色彩配置文件并非逐项移除，而是根本不会交给编码器，因此也就不会出现在输出结果中。需要了解两点：

• 像素相同，字节不同。JPEG 会再次经过编码器处理，因此副本与原件并非逐位完全相同，尽管看起来一样。如果这点很重要，请保留原件。
• 此处的其他所有写入工具也会产生相同的副作用。调整照片大小也会删除其 EXIF。

限制

• 拒绝处理超过 50 MB 的输入：无论图像在磁盘上的压缩效果如何，解码后都需要宽度 x 高度 x 4 字节的原始 RGBA 数据。
• 每边最多 10,000 px，先从文件头检查，再在解码后检查。
• 支持读取和写入：PNG、JPEG、BMP、GIF 和 TIFF，依据魔数而非文件扩展名检测格式。不支持 WebP、AVIF、HEIC 或 SVG，因为没有值得随附发布的纯 JavaScript 解码器，而且此服务不依赖原生组件。
• 动画 GIF 只读取第一帧。此服务不处理动画。
• 水印文本使用随附的 Open Sans 位图字体（8、16、32、64 和 128 px）绘制，并选择能放入图像的最大字号。字体中不包含的字符不会绘制，因此无法添加 CJK 水印。
• 不支持旋转、滤镜、色彩校正、OCR 或背景移除。此服务只处理尺寸和格式，不是图像编辑器。

数据存储方式

只会记录已执行的操作：${XDG_DATA_HOME:-~/.local/share}/mcp-servers/image/operations.json，以纯 JSON 格式保存最近 500 条操作。图像会留在你放置的位置。每次写入记录时，都会对 .../image/.lock 加建议锁，因此同一数据目录下的两个客户端不会丢失记录；保存时会先写入临时文件，再重命名到目标位置。

如果记录无法读取或不是有效 JSON，绝不会将其视为“空记录”：系统会将其逐字节移至 operations.json.corrupt-<timestamp>，并在旁边放置标记。你要求处理的图像仍会写入磁盘，且在操作记录受到影响之前，图像文件就已保存；返回结果会告知你历史记录未能更新。

水印会读取整个套件共用的同一份配置文件 ${XDG_DATA_HOME:-~/.local/share}/mcp-servers/profile/business.json，该文件由 mcp-invoice 或 mcp-docx 中的 business_set 写入。系统不会凭空编造信息：如果没有存储名称，也没有传入文本，image_watermark 会拒绝执行，并告知你该运行哪个工具。

隐私

所有数据都保留在本地。此服务会读取和写入你机器上的文件，不会发起任何网络请求——无论是用于授权（密钥均离线验证）、获取字体还是遥测。你调整大小的客户端照片绝不会上传到任何地方，这正是此服务存在的全部意义。

搭配使用

• mcp-docx，在这里调整徽标大小，然后将其放入信头：先用 image_resize 将其调整到页眉高度，再由 .docx 写入器从磁盘读取该文件。
• mcp-pdf，在合并扫描件之前先缩小它们，以免合并后的 PDF 达到 40 MB。
• mcp-resume，为简历和申请表准备一张尺寸合适且不含元数据的头像照。
• office-suite，通过一次安装运行多个服务，并使用一个配置项。

故障排除

• npx 卡住或无法找到软件包：此软件包的 npm 发布仍在处理中。在发布完成前，请使用 .mcpb 捆绑包或上文的克隆并构建方式。
• “quality does not apply to a PNG output”：将输出写入 .jpg out_path，或传入 max_width。请参阅上文的章节。
• “declares NxN pixels ... and was refused before decoding”：文件声明的画布每边超过 10,000 px。如果文件确实这么大，请使用能够分块流式处理的工具调整其大小；此服务会解码整张图片。
• “does not start with the magic bytes”：文件不是 PNG、JPEG、BMP、GIF 或 TIFF。常见原因是将 WebP 文件命名为 .png；请先转换格式。
• “already exists and nothing was written”：传入 overwrite: true，或使用不同的 out_path。
• 水印太小：捆绑的最大字体为 128 px，且会调整到不超过图片宽度的 80%。对于非常大的照片，请先调整大小，再添加水印。
• Node 版本：需要 Node >= 18。使用 node -v 检查。

采用 MIT 许可。支持邮箱：[email protected]

由 theluckystrike 构建。

将这些文档用作 MCP 服务

任何 MCP 客户端（Claude、Cursor、Windsurf、VS Code）都可以通过 GitMCP 直接读取此仓库的文档，无需安装：

• Docs MCP URL： https://gitmcp.io/theluckystrike/mcp-image