Image Puma

Image Puma

通过桌面应用或直接在你的 AI 中使用 MCP 服务，在本地批量准备 Web 图片。图片处理在本地运行；Image Puma 不会上传你的图片、不要求你注册账号，也不会做其他任何无聊的事。所有图片处理都在本地完成。

使用应用

从 GitHub Releases 下载当前版本的 Image Puma 桌面安装程序：

• macOS（Apple Silicon）：Image-Puma.dmg
• Windows：桌面安装程序即将推出 — Windows 已可通过下方的 MCP 服务在 Claude 中获得完整支持；也可以在 Windows 设备上从源码构建，运行 npm install && npm run make（需要 Python 3.11，并且需要有权访问受限的 RMBG-2.0 model，用于移除背景）。

桌面应用和 MCP 服务是相互独立的组件 — 根据你的需求，可以单独安装其中之一，也可以同时安装。

我们的安装程序未经代码签名。这是一款免费应用，我们不太愿意仅仅为了让操作系统眼中的它成为“真正的应用”，而每年支付 Apple 99 美元的开发者费用。因此：

• macOS 首次启动时会阻止此应用。要打开它，请右键点击应用并选择“打开”，或前往“系统设置” →“隐私与安全性”→“通用”，然后点击“仍要打开”。

• Windows 会显示 SmartScreen 警告。点击“更多信息”，然后点击“仍要运行”以继续。

在 Claude 中使用

Claude Desktop（一键安装）

一键安装 Claude Desktop 时使用 GitHub Releases 中的 .mcpb 捆绑包。

• 下载适用于你电脑的文件，
• 在 Claude Desktop 中打开该文件，
• 按提示选择 Image Puma 可以访问的图片文件夹，
• 如果 Claude Desktop 提示重启，请重启

使用以下链接：

• Apple Silicon Mac：image-puma-mcp-darwin-arm64.mcpb
• Windows：image-puma-mcp-win32-x64.mcpb

MCPB 安装程序会要求你选择允许访问的图片文件夹。Image Puma 只能从这些文件夹中读取文件，并向其中写入文件。

添加到 Claude Code

对于编码会话（优化项目资源、生成 favicon、为部署准备图片），只需运行一条命令即可添加 MCP 服务：

claude mcp add --scope user image-puma -- "$(command -v npx)" -y image-puma mcp serve --transport stdio --allow-dir ~/Pictures ~/Downloads ~/Documents

--scope user 会让 Image Puma 在你电脑上的所有仓库和终端中可用；省略它，则只会在你运行命令的文件夹中加载。将这些文件夹替换为你希望 Image Puma 能够访问的文件夹 — 添加项目文件夹即可让它优化该仓库中的图片，例如“压缩 assets/ 中的所有图片以用于 Web”。

请原样复制 "$(command -v npx)" 部分 — 运行命令时，它会展开为 npx 的完整路径。直接注册 npx 看起来没问题，但随后会连接失败，因为 MCP 服务启动时使用的是精简的 PATH，其中不包含 nvm、fnm 或 Volta 等 Node 版本管理器。请参阅下方的未找到 Node。

然后启动一个新的 Claude Code 会话（在 VS Code 扩展中开始新对话，或在终端中重新运行 claude）— MCP 服务及其命令会在会话启动时被发现，因此已打开的会话看不到它。随时运行 claude mcp list 检查连接状态。

如果你克隆了此仓库，请改为将命令指向你的本地构建（绝对路径）：

npm install && npm run build:mcp
claude mcp add --scope user image-puma -- "$(command -v node)" /absolute/path/to/Image-Puma/dist/cli.js mcp serve --transport stdio --allow-dir ~/Pictures

其他 MCP 客户端

使用 npx 安装开发版本，并指定允许访问的文件夹的绝对路径：

{
  "mcpServers": {
    "image-puma": {
      "command": "/usr/local/bin/npx",
      "args": [
        "-y",
        "image-puma",
        "mcp",
        "serve",
        "--transport",
        "stdio",
        "--allow-dir",
        "/Users/you/Pictures"
      ]
    }
  }
}

在 mcpServers JSON 中的所有位置都使用绝对路径 — 既包括允许访问的文件夹，也包括 command。在终端中运行 command -v npx，并将输出内容粘贴到 /usr/local/bin/npx 所在位置。在 Windows 原生环境中，请使用 "command": "cmd"，并将 "/c" 和 "npx" 作为前两个参数。

使用效果

安装完成后（无论采用上述哪种方式），只需用日常语言向 Claude 提出要求：

你： 压缩 ~/Pictures/site 中的图片，以便上传到网站

Claude： 计划如下：接受了 14 张图片，将转换为 WebP 格式、调整为适合网页的尺寸并移除元数据。我会列出确切的输出路径，确保不会覆盖任何文件。现在运行吗？

你： 是

Claude： 完成——14 张图片全部成功，输入 41.8 MB，输出 3.6 MB。

Image Puma 始终先制定计划：你可以看到它接受了哪些文件、会应用哪些设置，以及每个输出文件的保存位置——只有你确认后才会写入磁盘。它也只能访问你在安装时授权的文件夹。

提示词示例：

• 压缩这些图片以便上传到网站：/Users/you/Pictures/site
• 压缩这些图片以便通过电子邮件发送：/Users/you/Desktop/photos
• 移除这些图片的元数据：/Users/you/Downloads
• 从这些图片生成缩略图：/Users/you/Pictures/products
• 从 /Users/you/Projects/my-app/logo.png 生成 favicon 和应用图标包，输出到 /Users/you/Projects/my-app/public

/image-puma 命令

Image Puma 提供了一个斜杠命令，可让 Claude 使用 Image Puma 工具处理你描述的任意图片任务——先制定计划，确认后再运行：

/image-puma compress everything in ~/Pictures/site for the web

在 Claude Code 终端中输入 /image-puma，命令菜单会找到它（完整名称为 /mcp__image-puma__image-puma）。在 Claude Desktop 中，同一提示词位于聊天输入框的 + 菜单下，列在 Image Puma 项目中。

如需使用也能在 VS Code 扩展中运行的裸 /image-puma 命令（其命令菜单不会列出 MCP 提示词），请将以下内容保存为 ~/.claude/commands/image-puma.md：

---
description: Batch image work via Image Puma (compress, resize, strip metadata, thumbnails, favicons)
---

Use the Image Puma MCP tools for this local image task: $ARGUMENTS

If no task was given, ask which images to process and what result is wanted.

Create a plan first with image_puma_plan — plan only, do not run it yet. Pick a preset with image_puma_list_presets, or use custom settings (schema via image_puma_settings_schema). Show the returned plan, warnings, and planned output paths, and call image_puma_run only after the user explicitly confirms.

之后，新会话中就能在任何地方使用 /image-puma——包括终端和 VS Code——前提是已注册上文“添加到 Claude Code”中的 MCP 服务。

可通过 image_puma_generate_favicon 快速生成 favicon。

故障排除

找不到 Node

claude mcp list 显示 Image Puma 运行失败，并提示 ENOENT: Executable not found in $PATH: "npx"（或 "node"）：

image-puma: npx -y image-puma mcp serve ... - ✘ Failed to connect

MCP 客户端会以精简的 PATH 启动服务，不会加载 ~/.zshrc 或 ~/.bashrc，因此通过 nvm、fnm、Volta 或 asdf 安装的 Node 对它不可见，尽管终端可以正常找到。请使用绝对路径重新注册：

claude mcp remove image-puma -s user
claude mcp add --scope user image-puma -- "$(command -v npx)" -y image-puma mcp serve --transport stdio --allow-dir ~/Pictures

然后启动新会话，再次检查 claude mcp list。

使用 nvm 时有一点需要注意：command -v npx 会解析为固定版本路径，例如 ~/.nvm/versions/node/v24.13.1/bin/npx，升级 Node 后该路径便会失效。升级后重新运行上面的两条命令即可；或者将 Image Puma 指向不由 nvm 管理的 Node（/opt/homebrew/bin/node 或 /usr/local/bin/node），以确保路径持续有效。Image Puma 需要 Node 20.3.0 或更高版本。

Claude Desktop 用户无需处理这些步骤——上方的 .mcpb 包自带 Node 运行时。

Windows 将 npx image-puma 解析到本地检出目录

在 Windows 上，如果在名为 image-puma 的目录中（不区分大小写）运行 npx image-puma ...，例如在此仓库的克隆目录中，npm 可能会将软件包名称解析为该本地目录，而不是已发布的软件包。如果尚未构建该检出目录，命令会报错：'image-puma' is not recognized as an internal or external command。

请在其他工作目录中运行 npx image-puma ... 命令。从克隆目录进行开发时，请使用 npm run build:mcp 构建，并让 MCP 服务直接指向本地的 dist/cli.js，而不是通过 npx 调用它。

其他问题

运行内置检查，它会报告 Node 版本、Sharp、ExifTool，以及获准访问的文件夹是否确实可写：

npx -y image-puma mcp doctor --allow-dir ~/Pictures

贡献

Image Puma 由 Pantheon Network 按现状发布。 我们目前不会主动修复 bug 或审查拉取请求。如果你愿意接手维护工作，请联系我们。 开发环境设置、检查和构建流程见 CONTRIBUTING.md。

支持矩阵

格式和操作系统行为记录在 docs/support-matrix.md 中。处理 HEIC/HEIF 时会优先使用 Sharp。macOS 可以通过 sips 回退到 ImageIO。Sharp 无法解码 HEVC 时，Windows 和 Linux 会回退到捆绑的 libheif 解码器。