Image Puma MCP server

Image Puma

Local batch image preparation for the web via a desktop app or directly within your AI via MCP server. Image processing runs locally; Image Puma does not upload your images, require an account, or do any other nonsense. All local image processing.

Use the App

Download the current Image Puma desktop installer from GitHub Releases:

• macOS (Apple Silicon): Image-Puma.dmg
• Windows: desktop installer coming soon — Windows is fully supported in Claude via the MCP server below, or build from source on a Windows machine with npm install && npm run make (needs Python 3.11 and access to the gated RMBG-2.0 model for the background remover).

The desktop app and MCP server are independent components — install either one on its own, or both together, depending on your needs.

Our installers aren't code-signed. This is a free app, and we'd rather not pay Apple's $99/year developer fee just to make it a "real app" in the eyes of the OS. As a result:

• macOS will block the app on first launch. To open it, right-click the app and select Open, or go to System Settings → Privacy & Security → General and click "Open Anyway."

• Windows will show a SmartScreen warning. Click "More info," then "Run anyway" to proceed.

Use It in Claude

Claude Desktop (one-click)

One-click Claude Desktop install uses the .mcpb bundles from GitHub Releases.

• Download the file for your computer,
• open it in Claude Desktop,
• choose the image folders Image Puma may access when prompted,
• then restart Claude Desktop if it asks

Use the following links:

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

The MCPB installer asks you to choose allowed image folders. Image Puma can only read from and write into those folders.

Add it to Claude Code

For coding sessions (optimizing project assets, generating favicons, prepping images for deploys), add the MCP server with one command:

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

--scope user makes Image Puma available in every repo and terminal on your machine; leave it off and it only loads in the folder you ran the command from. Swap the folders for whatever Image Puma should be allowed to touch — add a project folder to let it optimize the images in that repo, e.g. "compress every image in assets/ for the web".

Copy that "$(command -v npx)" part exactly — it expands to the full path of npx when you run it. Registering a bare npx looks fine and then fails to connect, because MCP servers are launched with a minimal PATH that doesn't include Node version managers like nvm, fnm, or Volta. See Node not found below.

Then start a new Claude Code session (new conversation in the VS Code extension, or a fresh claude in the terminal) — MCP servers and their commands are discovered at session start, so already-open sessions won't see it. Check it's connected any time with claude mcp list.

If you cloned this repo instead, point the command at your local build (absolute path):

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

Any other MCP client

Developer install with npx, using an absolute allowed folder path:

Shortened. The full README is on GitHub.