Image Compression Inside Claude Code: The Mochify CLI + MCP Guide

Can Claude Code use MCP?

Claude Code can use MCP, and it acts as a first-class MCP client: it connects to external servers, lists their tools with tools/list, and invokes them with tools/call per the protocol spec (Model Context Protocol: Tools). Anthropic added remote MCP support in June 2025, so Claude Code talks to both local processes and remote services.

In practice that gives you three transports worth knowing. Local stdio servers run as a child process on your machine. Remote http servers are the recommended transport for hosted connectors. The older sse transport still works but is marked deprecated in the docs, so prefer HTTP for anything remote (Claude Code MCP docs). For image compression that runs against files on your disk, the local stdio path is the one you want, and it is exactly what mochify serve provides.

The payoff is that "compress images in Claude Code" stops being a manual chore. Instead of describing an image to the agent or pasting it into a chat, you let Claude Code call a tool that does the encoding and hands back a file path. The agent keeps reasoning about your code; the bytes never clog its context window.

How to create and register a Claude MCP server

You register an MCP server in Claude Code with claude mcp add, and for a local tool you use the stdio transport (Claude Code MCP docs). The general shape puts options first, then the server name, then -- and the command to run:

# Syntax: options first, then name, then -- then the command
claude mcp add [options] <name> -- <command> [args...]

# Register Mochify's local MCP server
claude mcp add --transport stdio mochify -- mochify serve

That single command is the answer to "how to create a Claude MCP server" for the common case: you do not have to author a server from scratch when a tool already ships one. The mochify binary runs as a local MCP server when you launch it with mochify serve, and the line above tells Claude Code to start that process and speak MCP to it over stdio.

Install the binary first. It is a single Rust binary distributed three ways:

# macOS (Homebrew tap)
brew tap getmochify/mochify
brew install mochify

# Linux (raw binary)
curl -fsSL https://mochify.app/install.sh | sh

# From source
cargo install mochify

# Authenticate once: opens a browser OAuth flow
mochify auth login

mochify auth login is the standard auth path. It saves credentials to ~/.config/mochify/credentials.toml, and both the CLI and the local MCP server pick them up automatically, so there is no API key to paste into a config file or refresh later.

Once registered, check the server inside Claude Code:

claude mcp list        # show configured servers
claude mcp get mochify # details for one server
/mcp                   # inside Claude Code: status + tool count

If you would rather author your own server, Anthropic ships an mcp-server-dev plugin that scaffolds a Node or Python skeleton you wire back in with the same claude mcp add flow. For compressing images, though, registering mochify serve is the whole job.

If you want to set this up right now, the binary and quick-start are at mochify.app/docs.

Why image bytes are expensive

Returning raw image bytes into an agent's context is slow and costly; returning a file path or URL is cheap, and the protocol is built for it. The MCP tools spec defines resource_link and resource content types precisely so servers can hand back a handle instead of inlining a base64 blob (Model Context Protocol: Tools). Claude Code reinforces this with hard limits: it warns when any MCP tool output exceeds 10,000 tokens and enforces a default cap of 25,000 tokens, which you can raise with MAX_MCP_OUTPUT_TOKENS (Claude Code MCP docs).

The cost side is real. Images are tokenized alongside text and billed from the same pool; Anthropic's token-counting endpoint counts images and PDFs just like prompt text (Anthropic token counting). With 2026 flagship pricing in the region of $5 per million input tokens and $25 per million output tokens on a 1M-token context window, a batch job that inlines hundreds of images can quietly burn tens of thousands of tokens per run before the model has done any useful reasoning.

This is the core reason the local MCP path matters for developers. Mochify's local MCP server (mochify serve) returns file paths and metadata, not image bytes, so the image data never enters the agent's context at all. The agent sees "compressed /assets/hero.avif, 2.4 MB to 410 KB" as a short string and keeps going. The direct CLI behaves the same way: bytes flow from your disk to the encoder and back to disk, with only a one-line summary surfacing to the session.

Three real workflows

The patterns developers already use for image optimization, pre-commit hooks, CI actions, and build steps, map cleanly onto Claude Code. Here are three that earn their place.

1. CLI as a pre-commit / build step

Run the mochify CLI as a build step so no oversized asset gets committed. This mirrors the well-established pattern of wrapping an optimizer (oxipng, ImageOptim CLI) in a pre-commit hook, but with Magic Flow you describe the intent instead of memorizing flags:

# Compress staged images before they land in a commit
mochify -p "compress for web, convert PNGs to AVIF, strip EXIF" ./src/assets/*.png

Because the CLI is a client over the API and returns paths to disk, it slots into a Husky hook or an npm script the same way any other formatter would. Strip EXIF here too: it removes location and camera metadata before the file ever reaches your repo. (More on why that matters in our EXIF data risks guide.)

mochify serve as a local MCP tool in a session

Let the agent find and fix images interactively. Once mochify serve is registered, you can ask Claude Code to do multi-step asset work it could not do with a plain CLI: "Find all images contributing to poor LCP on the homepage, re-encode the hero to AVIF, add a WebP fallback in the <picture> element, and update the srcset." The agent decides which images matter, calls the Mochify tool to compress them, and edits the markup, all in one loop. This is the workflow a plain build step cannot match, because it couples compression with code changes and reasoning.

Non-interactive mode in CI

Pipe Claude Code's headless mode into a CI job for repo-wide passes. Claude Code supports a non-interactive claude -p mode you can drive from a GitHub Action, combining a git diff of changed assets with a request to compress them and summarize the result. The Mochify MCP tool does the encoding; the action commits the optimized files back to the branch. This is the agent-driven version of the many CI actions that compress images on pull requests, with the difference that the agent can also adjust the code that references those assets.

Zero-retention and client assets

"Zero-retention" means a service does not persist your prompts or files beyond transient processing, and for agencies under NDAs or GDPR that is a contractual concern, not a nicety. Recent AI image services define the term concretely as prompts and outputs that are not logged, not used for training, and deleted immediately after delivery. Data-processing agreements increasingly require exactly this: a named retention period, a deletion procedure, and no secondary use such as model training.

For a coding agent the local-versus-remote split is what decides your exposure. A local tool that runs on your machine keeps bytes off third-party servers except where it explicitly calls an API. A remote service receives whatever it needs to do the job, and is then governed by that provider's retention and training policy. This is worth checking carefully for your own setup, too: Anthropic's consumer plans moved in 2025 to an opt-in model where chats and coding sessions can be retained and used for training for up to five years if you opt in, while API and enterprise products keep the stricter no-training stance. If you are handling client assets in Claude Code, confirm which plan and settings you are on.

Mochify's position here is deliberately narrow and honest. On the CLI and mochify serve paths, the original is streamed into RAM at api.mochify.app, wiped immediately, and never written to our disks or logged; the compressed output returns straight to your local disk with no server-side pickup store. That is zero-retention end-to-end for the developer surfaces. We do not claim your images never leave your laptop, because they travel to the API for encoding. If you need an even tighter boundary, our self-hosting guide walks through running an optimization API behind your own firewall.

The performance payoff

Optimizing images is the single biggest lever on Largest Contentful Paint, and modern formats compress dramatically better than JPEG. Google's web.dev guidance is consistent that LCP is usually dominated by a hero image, so compressing, correctly sizing, and modernizing that image is the highest-impact change you can make (web.dev: optimize LCP).

The format gains are large and measurable. WebP typically runs 25-35% smaller than JPEG at similar quality, and AVIF often lands around 50% smaller than JPEG and 20% smaller than WebP. Crucially, AVIF is now production-ready: caniuse reports support across Chrome (85+), Safari (16.4+), Firefox (93+), Edge (121+), and most mobile browsers, putting global coverage near 94% (caniuse: AVIF). JPEG XL is the exception, still disabled by default in Chrome and Firefox as of early 2026, so ship it only with fallbacks and feature detection.

In concrete terms, a 2.4 MB JPEG hero re-encoded to AVIF at web quality typically lands around 410 KB, an 83% reduction, with no visible quality loss on a standard display. Do that across a batch and you are shipping a fraction of the bytes. When you would rather keep the familiar JPEG container, Mochify uses Google's jpegli encoder to squeeze more quality per byte out of standard JPEG; our jpegli guide covers when that is the right call.

Cheat sheet

FAQ