mochify-cli

A command-line tool and MCP server for mochify.app — a fast, privacy-first image compression and conversion API powered by a native C++ engine.

Compress and convert images to modern formats (AVIF, JXL, WebP, Jpegli) from your terminal, work on PDFs, or give AI assistants like Claude direct access to the same engine over the Model Context Protocol — either as a local stdio server (mochify serve) or the hosted one at mcp.mochify.app, which needs no install at all.

Jump to: Installation · CLI usage · PDF processing · MCP server · Plans

Installation

macOS (Homebrew):

brew tap getmochify/mochify
brew install mochify

Windows (Scoop):

scoop bucket add mochify https://github.com/getmochify/scoop-mochify
scoop install mochify

Linux / WSL:

# x86_64
curl -L https://github.com/getmochify/mochify-cli/releases/latest/download/mochify-linux-x86_64 -o mochify
chmod +x mochify
sudo mv mochify /usr/local/bin/

# arm64
curl -L https://github.com/getmochify/mochify-cli/releases/latest/download/mochify-linux-arm64 -o mochify
chmod +x mochify
sudo mv mochify /usr/local/bin/

Cargo (all platforms):

cargo install mochify

Requires Rust. Easiest option on Linux/WSL if you already have the toolchain.

Manual: All binaries at Releases.

From source:

cargo install --path .

Authentication

Sign in with your mochify.app account to unlock your full quota:

mochify auth login

This opens your browser, where you sign in and authorize the CLI. Credentials are saved automatically to ~/.config/mochify/credentials.toml — no environment variables or manual key copying required. Both the CLI and MCP server pick them up automatically.

On a machine without a browser (over SSH, say), sign in with a code instead — open the link it prints on any device and type the code:

mochify auth login --no-browser

mochify auth status   # check whether you're signed in
mochify auth logout   # remove saved credentials

Without an account you get 3 images per batch (IP-based). With a free account: 25 images/month. Sign up at mochify.app.

CLI Usage

mochify [OPTIONS] <FILES>...

Options

Examples

# Convert to AVIF
mochify photo.jpg -t avif

# Resize and convert to WebP
mochify photo.jpg -t webp -w 800

# Batch convert a folder to AVIF at 1200px wide
mochify ./images/*.jpg -t avif -w 1200 -o ./compressed

# Natural-language prompt — let the AI pick the right params
mochify photo.jpg -p "convert to avif, 1200px wide"
mochify photo.jpg -p "optimise for eBay"
mochify photo.jpg -p "remove background and convert to WebP"
mochify photo.jpg -p "resize to 50%, strip EXIF, keep as WebP"

# Custom output name
mochify photo.jpg -t webp -n hero
mochify product.jpg -p "optimise for Shopify" -n product-main

# Pipe file paths from stdin
find . -name "*.jpg" | mochify -t webp -o ./out
cat images.txt | mochify -p "convert to avif 1200px wide" -o ./compressed
ls *.heic | mochify -t jpg

Quality

Quality is chosen automatically unless you say otherwise.

# Fixed quality
mochify photo.jpg -t webp -q 70

# Let saliency pick it — detailed subjects keep more, flat areas less
mochify photo.jpg -t avif --smart-compress

# Smallest file to serve from a web server
mochify photo.jpg -t webp --optimize-for-web

# Brighten a dark photo
mochify photo.jpg --brightness 30

# Pixel-exact
mochify scan.png -t webp --lossless

--lossless only works for jxl, webp and png — jpg and avif are rejected before the request goes out. It overrides -q and --smart-compress, and the output is usually larger than the input: lossless preserves pixels, not file size. A source that is already lossy (JPEG, AVIF, HEIC) comes back as the best lossy encode instead, since nothing can restore what that file discarded — the CLI says so when that happens.

Cropping to a region

--crop finds the subject itself. --region is for when you — or the AI assistant driving the MCP server — already know which part of the picture you want:

# The bottom-left quarter
mochify photo.jpg --region 0,0.5,0.5,0.5

# A region, then sized: -w/-H apply to the cropped part
mochify photo.jpg --region 0.2,0.1,0.6,0.8 -w 800 -t webp

The four numbers are x,y,width,height as fractions of the image (0 to 1), measured from the top-left of the picture as it displays — the right way up, even for a phone photo stored sideways. Fractions rather than pixels so the same box works whatever size the image is viewed at. A value above 1 is refused before the request goes out, since that is almost always a box in pixels. The region is cut first: -w/-H, --crop, --rotation and --remove-bg all act on it. --verbose prints the pixel rectangle that was actually cut.

Over MCP this is how an assistant can crop to content — "crop to the feet", "just the logo": it looks at the image itself, picks the box, and Mochify only ever receives the four numbers.

Redaction

Hide faces, number plates, addresses or anything else before an image goes anywhere:

# Every face, found automatically
mochify family.jpg --redact faces

# A number plate, as a box (fractions of the upright image, like --region)
mochify car.jpg --redact 0.38,0.71,0.24,0.08

# Both, softened with a blur instead of a solid fill
mochify street.jpg --redact "faces;0.38,0.71,0.24,0.08" --redact-style blur

Separate entries with ; — the , belongs to the box. fill (solid black) is the default and the one to use for anything that must stay secret; blur is for the look of a blurred face, and blurred text or faces can sometimes be recovered.

Redaction always strips metadata (EXIF can hold a thumbnail of the original) and removes any HDR gain map (which holds the scene's structure), even if you asked to keep them. faces is best-effort — it can miss small faces and side profiles — so the CLI says when it found none. Check the output before sharing it.

HDR (Ultra HDR gain maps)

--hdr controls the Ultra HDR / ISO 21496-1 gain map that makes a photo render with real headroom on an HDR display.

Only jpg output can carry a gain map (jxl carries HDR by a different route; avif, webp and png cannot), so pair it with -t jpg. It is also skipped alongside --clarity or --remove-bg, which change the base the gain map is a ratio to. The CLI reads the X-Mochify-HDR response header and tells you when the output ended up with no gain map.

# Keep the headroom an iPhone photo already captured, converting to JPEG
mochify IMG_1234.heic -t jpg --hdr

# Give an SDR photo a gain map
mochify photo.jpg --hdr generate

# Or just say so
mochify photo.jpg -p "make this HDR"

Output file naming

By default, when the output format and directory match the input, the result is saved as {name}_mochified.{ext} so it's always clear something happened. If that file already exists, a numeric suffix is added (_1, _2, etc.). When the format changes (e.g. .jpg → .webp), the extension change is already unambiguous so no suffix is added.

Use -n, --name to set an explicit base name: mochify photo.jpg -t webp -n hero saves hero.webp. The prompt path also supports this: mochify *.jpg -p "optimise for Shopify, name them product" will produce product.webp, product_1.webp, etc.

PDF processing

PDFs are detected automatically by the .pdf extension, and --op picks what to do with them. (PDFs and images can't be mixed in a single command — run them separately.)

create is the exception: its inputs are images, so there is nothing in a .jpg to route on. Pass --op create, or just say "pdf" in a prompt — mochify *.jpg -p "convert to pdf" builds one too.

# Make a PDF smaller without touching the text
mochify report.pdf --op optimize -q 75 --dpi 150

# Pull the embedded images out as WebP, capped at 1600px
mochify brochure.pdf --op extract -t webp --max-width 1600

# Render pages to PNG at 150 DPI, or high-res JPEGs for print
mochify document.pdf --op rasterize -t png --dpi 150
mochify document.pdf --op rasterize -t jpg --dpi 300 -q 90

# One PDF per page
mochify document.pdf --op split

# Build a PDF from images (one page per image, in the order given)
mochify page-*.jpg --op create --page a4 -n scanned
mochify page-*.jpg --op create --no-combine   # one PDF per image, as a zip

# Or describe it in natural language
mochify report.pdf -p "compress this pdf"
mochify brochure.pdf -p "get the photos out as png"
mochify document.pdf -p "split into pngs"
mochify page-*.jpg --op create -p "one a4 pdf, good quality"

# A prompt that says "pdf" on image inputs implies --op create
mochify page-*.jpg -p "convert to pdf"
mochify scan-*.png -p "one a4 pdf, good quality"
mochify shot-*.jpg -p "each image as its own pdf"

Outputs are named after the input: report_compressed.pdf, brochure_images.zip, document_rasterized.zip, document_pages.zip, and <first image>.pdf for create (override with -n).

optimize, extract, rasterize and split require a paid plan; create works on every plan, including Free.

MCP server

Mochify speaks MCP two ways. Both call the same engine at api.mochify.app, where encoding happens in RAM and the original is discarded immediately. The difference is where your files live.

Reach for hosted when the agent has no filesystem — Claude.ai, a hosted runtime, anything talking to images that already live on the web. Reach for local when the files are on your machine, which is most of the time: nothing but a path and a byte count ever enters the model's context.

Both can run side by side in the same client with independent tokens.

Hosted (no install)

Register https://mcp.mochify.app as a remote MCP connector and complete the OAuth flow once. No API key to copy or rotate.

• Claude.ai — Settings → Connectors → Add custom connector
• Claude Desktop — Settings → Connectors, or a "type": "http" entry in the config
• Cursor, Windsurf, Gemini, any client with remote MCP support — same URL

Or install it from Smithery:

smithery badge

Results come back as a download URL with roughly a five-minute expiry, held in an in-memory pickup store until fetched or the TTL lapses. Originals are never stored. This is the one path that is not zero-retention end to end — see why we relaxed zero retention for MCP.

Local (stdio)

Run mochify auth login first, then point your client at the binary:

{
  "mcpServers": {
    "mochify": {
      "command": "mochify",
      "args": ["serve"]
    }
  }
}

Claude Desktop's config lives at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS. Restart the client afterwards; the server picks up your saved credentials automatically. Any stdio MCP client works the same way — Cursor, Continue, Cline, Claude Code.

Set MOCHIFY_API_KEY instead for CI, or leave auth off entirely to run on the anonymous free tier.

Tools

Both servers expose the same four tools. The difference is how files get in and out: the local server takes paths and writes to disk, the hosted one takes URLs or base64 and hands back a short-lived download URL.

squish parameters: file_path, type, width, height, crop, rotation, quality, smart_compress, lossless, optimize_for_web, brightness, clarity, remove_background, background, strip_metadata, hdr, output_dir, output_name.

pdf parameters: file_path, op, type, dpi, quality, max_width, min_size, output_dir.

pdf_create parameters: file_paths, page, quality, dpi, max_width, combine, output_name, output_dir.

check_usage takes no parameters.

Every tool reads and writes the filesystem itself, so the agent never has to load an image to process it. Responses carry the saved path plus whatever the API reported: how much smaller the PDF got, whether a gain map survived, whether a lossless request had to fall back to lossy, and how much quota is left.

Usage

Describe what you want in natural language, with the full path to your file:

"Convert /Users/me/Desktop/photo.jpg to AVIF at 1000px wide"

"Compress all the JPEGs in /Users/me/projects/blog/images/ to WebP and save to /Users/me/projects/blog/compressed/"

"Optimise /Users/me/Desktop/product.jpg for eBay"

"Remove the background from /Users/me/Desktop/shirt.png and save as WebP"

"Compress /Users/me/Desktop/report.pdf — it's too big to email"

"Rasterize /Users/me/Desktop/report.pdf to PNGs at 200 DPI"

"Make /Users/me/Desktop/sunset.jpg HDR"

"Brighten /Users/me/Desktop/dim.jpg a bit and optimise it for my website"

"Turn the scans in /Users/me/Desktop/receipts/ into one A4 PDF"

API

Powered by https://api.mochify.app — /v1/squish for images, /v1/pdf for PDF optimize/extract/rasterize/split/create. Files are processed in RAM and never written to disk.

One operation is one output image. Compress, convert, resize and rotate the same file and it stays one operation; ask for two formats at two sizes and that is four. PDF optimize, extract, rasterize and split need a paid plan (Day Pass counts); create works on every plan including Free.

Visit mochify.app for the web interface, pricing, and API docs.

Questions

Ask in GitHub Discussions — answers stay searchable there, which a support email thread does not. Bugs and feature requests belong in Issues. For anything account or billing related, email hello@mochify.app.

Listed in the official MCP Registry as mcp-name: app.mochify/mochify.