Compress Images With Claude Code and Codex Using an MCP Server

Connect Smol once, then ask in plain language. Smol’s MCP server gives Claude Code compress, convert, upscale and strip-metadata tools with real parameters: format, quality, resize, output location and metadata handling. You describe the result; the agent calls the tool.

If you want Claude Code to compress images without a tool like that, it falls back on whatever is installed: sips, ImageMagick, cwebp or a Node package. That works for one file. The weak point is repeatability. Each run picks its own quality, and the agent reads its own shell output instead of a structured result. An MCP tool makes the settings explicit and the output checkable, so two runs a week apart produce the same kind of file. Our guide to compressing images before a commit covers why the repo is where this matters most.

The tightest ones are a per-image cap, a pixel cap and a repository cap. Each row links to the vendor’s own documentation, read on 11 October 2026. Model limits change with releases, so recheck a number before you build on it.

Two points matter here. First, base64 adds about a third, so a 10 MB base64 cap means a file of roughly 7.5 MB, and the 5 MB cloud-platform cap means about 3.75 MB. Second, a bigger image does not buy more detail. Anthropic downsizes anything past the tier’s long edge: a 2000 × 1500 image becomes 1269 × 952 on the standard tier and costs 1564 visual tokens, against 3888 tokens on the high-resolution tier. Pre-resizing saves upload bytes either way.

The agent starts or connects to a local process and calls its tools by name. For an MCP server image compression tool, the work happens in that process, on your machine, so the files never need a network hop. Smol’s server is the app you already run.

Claude Code

Claude Code adds servers with claude mcp add [options] <name> -- <command>, and stores them in one of three scopes: local (the default, just you in this project), project (shared through .mcp.json) or user (every project, kept in ~/.claude.json), per the Claude Code MCP docs. Smol’s Connect button writes its own entry into the client’s settings, keeps your other servers, and declines to overwrite a file it cannot read safely.

Can Codex compress images the same way?

Yes. Codex uses the same protocol. Its docs give codex mcp add <name> -- <command> and a [mcp_servers.<name>] table in ~/.codex/config.toml, with a startup timeout of 10 seconds and a tool timeout of 60 seconds by default (Codex MCP docs). If one call runs long on a big folder, those two fields are the ones to raise. Smol also connects to Google Antigravity, added in Smol 1.0.35.

What does the agent get back?

Structured results, and the output budget matters. Claude Code warns when a tool returns more than 10,000 tokens and caps output at 25,000 by default, adjustable with MAX_MCP_OUTPUT_TOKENS. Ask the agent for a summary (file, size before, size after), not a dump of every field, when you process hundreds of files.

Give the agent a table, not a vibe. Smol’s image default is quality 75 with metadata stripped, and it resizes to fit inside 2000 × 2000 px unless told otherwise, so say the size you want every time. The numbers below are starting points we chose, not measured thresholds. Look at one output before you run the folder.

Screenshots deserve the extra care. Anthropic warns that heavy lossy compression “can introduce artifacts that are detrimental to model performance”, and says JPEG compression can make text difficult to read, so keep quality higher when the agent has to read the picture. Metadata is not a factor for the model: Anthropic states that Claude does not parse or receive image metadata. Stripping it still matters for what you publish.

Target size is a band, not a ceiling, and it is slow, about 28 seconds for one 768 × 512 image, so reserve it for the few files that miss a cap. For scale, on 24 small Kodak test photos (768 × 512 JPEGs, default settings) Smol’s JPEGs came out 69.3% smaller, and PNG compressed to AVIF at quality 65 saved 92.1%. Those are small film photographs, so your files will differ; the method is on the benchmark page.

It takes about two minutes, once per Mac.

1. 1

   Open Smol for AI

   Launch Smol and choose “Smol for AI” in the sidebar.

2. 2

   Press Connect next to your client

   Claude Code, Codex or Google Antigravity. Smol adds itself to that client’s MCP settings.

3. 3

   Copy the full AI guide into the agent

   Use “Copy full AI guide” so the agent knows every tool, format and setting.

4. 4

   Give the task with the numbers in it

   For example: compress the images in this absolute folder path to WebP at quality 75, maximum dimension 1600, and report size before and after per file.

5. 5

   Check the largest output and one image

   Open the biggest result and one text-heavy screenshot. Fix the setting, not each file.

6. 6

   Commit the compressed copies

   Outputs are copies with a _compressed suffix by default, so decide which set the repo keeps.

Pick the trigger. An agent session handles a task on request. A watched folder handles files as they arrive. A Finder Quick Action handles a right-click. For a pipeline on a server, the answer is different.

• Inside an agent session: add a line to your project’s agent instructions such as “before committing images, compress them with Smol at quality 75”, so the agent applies the same settings each time. This is how an AI agent optimizes assets without a reminder.
• Watched folders: good for fresh screenshots and camera exports. They can make already-optimized files larger, so never point one at your repo’s assets folder. See the watched folder guide.
• Finder Quick Action: a right-click for humans on the team, described in adding a Compress Quick Action.
• CI on Linux: Smol is a Mac app and cannot run there. Use an image library in the build, or the Smol API for server-side compression.

For a team, Smol is $29 once for one Mac. Team is $49 once for three Macs, and Enterprise is $20 a seat for 5 to 500 seats, managed from one dashboard. There is no subscription and no per-file cap. Presets are saved on each Mac, so write your settings in the repo’s agent instructions and have each developer recreate the preset. Framework-specific advice is in Next.js and React image assets, and README images are covered in GitHub README media.

Start with what is free and already there. The comparison below is fair to each option.

More on the built-in option is in the sips command guide, and the full methods comparison tests the rest. Our web developer guide covers formats and delivery.

Your pipeline runs on Linux or in CI. Smol is macOS only and is not a build-time tool. Put an image library in the build, or use the Smol API.

You need lossless output. Smol always re-encodes images and has no lossless mode. For pixel-identical results, ImageOptim is the answer, shown in our head-to-head test.

You need SVG, JPEG XL or responsive sets. Smol writes neither SVG nor JPEG XL, and one job produces one size, so several widths of one image take separate runs.

You compress a file every few weeks. Open Smol and drag it in. The MCP layer pays off when the work repeats or already happens inside an editor session. For other teams on the Mac, the web agencies page covers client sites.