Compressing Images from Your AI Coding Assistant with MCP

There's a specific kind of task that's too small to write a script for and too tedious to do by hand. "Convert every JPEG in this assets folder to WebP at quality 80, but skip the ones already under 100 KB, and tell me how much I saved." You could write that in sharp in twenty minutes. You could do it manually in forty. Or you could type it as a sentence and have your AI assistant do it in one turn.

That's what the Model Context Protocol enables, and image optimization turns out to be an unusually good fit for it. This guide covers how to wire up mcp-compressfile, the open-source MCP server for compressfile.pro, so Claude, Cursor, or any MCP-compatible agent can compress, convert, resize, deduplicate, and audit images on your local disk.

---

Table of Contents

1. What MCP Actually Is
2. Why Image Work Suits an Agent
3. Installing mcp-compressfile
4. Connecting It to Claude Desktop
5. The Sixteen Tools
6. Supported Formats and Behaviour
7. The Safe Workflow: Estimate → Preview → Compress → Report
8. Example Prompts That Work
9. Privacy and Why Local Matters Here
10. Frequently Asked Questions

---

1. What MCP Actually Is

The Model Context Protocol is an open standard for giving AI assistants access to tools and data. An MCP server exposes a set of functions with typed parameters; an MCP client — Claude Desktop, Cursor, and a growing list of others — discovers those functions and lets the model call them.

The important architectural detail for our purposes: the server runs on your machine, as your user, with your file permissions. It's a local process the client starts over stdio. It is not a cloud API, and no data is routed through a third party unless the server itself makes network calls.

mcp-compressfile makes none. It's a Python process wrapping Pillow. Your images are read from disk, transformed in memory, and written back to disk.

---

2. Why Image Work Suits an Agent

Not every task benefits from being handed to a model. Image optimization does, for four reasons:

• The parameters are fiddly and situational. Quality 80 or 85? Resize to 1600 or 1920? WebP or AVIF? These depend on content in ways that are annoying to encode in a script but easy to describe in a sentence.
• It's inherently multi-step. Find the large files, check what format they are, estimate the savings, run the batch, verify the output. That's five tool calls an agent can chain without you supervising each one.
• The work is verifiable. Unlike most agent tasks, you get hard numbers back — bytes in, bytes out. You can tell immediately whether it worked.
• It's low-stakes and reversible if the tooling is designed for it, which is why undo_last_batch and a dry-run estimator matter more than they sound.

The realistic use case isn't replacing your build pipeline. It's the ad-hoc middle ground: a folder of screenshots for docs, a batch of product photos a client just sent over, an assets/ directory that's quietly grown to 40 MB.

---

3. Installing mcp-compressfile

The server is a single Python file, MIT licensed, at github.com/lexusmarchuk/mcp-compressfile.

How to install

1. Check your Python version. 3.9 or later is required.

python --version

2. Install the dependencies:

pip install "mcp[server]" Pillow pillow-avif-plugin imagehash

3. Clone the repository:

git clone https://github.com/lexusmarchuk/mcp-compressfile
cd mcp-compressfile

4. Note the absolute path to server.py. You'll need it in the next step.

pwd

5. Verify AVIF support loaded correctly, since this is the most common install problem:

python -c "from PIL import Image; import pillow_avif; print('AVIF OK')"

If that errors, AVIF output won't work but everything else will. On Linux you may need libavif from your package manager first.

A note on virtual environments: if you install into a venv, the command in your client config must point at that venv's Python interpreter, not the system one. This trips up more people than any other step.

---

4. Connecting It to Claude Desktop

How to configure the client

1. Open Claude Desktop → Settings → Developer → Edit Config.
2. Add the server block, substituting your real absolute path:

{
  "mcpServers": {
    "mcp-compressfile": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

3. Windows users: use forward slashes — C:/Users/You/Pictures, not backslashes. Backslashes in JSON need escaping and this is a frequent source of silent failures.
4. Restart the client completely. Not just the window — quit and reopen.
5. Confirm the tools loaded. A hammer icon appears in the chat input when the server has connected. Click it to see all sixteen tools listed.
6. Smoke-test it with something read-only:

List all images in /Users/you/Pictures and tell me which are larger than 1 MB.

If the model calls list_files and find_large_images and returns real filenames, you're connected.

For Cursor and other clients: the same JSON block goes in that client's MCP configuration. The protocol is standard; only the location of the config file differs.

---

5. The Sixteen Tools

The tool surface is deliberately split so an agent can inspect before it acts.

File and folder operations

Analysis and metadata

Transformations

Reporting and agent helpers

Two behaviours worth calling out because they prevent common mistakes:

• EXIF auto-rotation is applied before any transformation. Photos shot in portrait on a phone carry an orientation flag rather than rotated pixels. Tools that ignore it produce sideways output — this one doesn't.
• Bulk operations accept glob patterns, so /data/**/*.png recurses through subdirectories. You don't have to enumerate folders.

---

6. Supported Formats and Behaviour

Accepted input: .png, .jpg, .jpeg, .webp, .tiff, .bmp, .avif

The JPEG row matters more than it looks. If you convert a transparent PNG to JPEG, the transparent regions become white — because JPEG has no alpha channel and something has to fill the space. That's correct behaviour, but it will surprise you if you batch-convert a folder of logos. Use WebP or keep PNG when transparency matters.

---

7. The Safe Workflow: Estimate → Preview → Compress → Report

The tool set is designed around a specific sequence. Following it prevents the two failure modes that make people distrust automated compression: over-compressing, and not knowing what changed.

How to run a compression job safely

1. Survey first. Ask the agent to list files and find anything above a size threshold. You now know the scope of the problem before touching anything.

Find every image in /project/assets larger than 400 KB.

2. Ask for a format recommendation. suggest_format analyses the actual content rather than guessing from the extension.

Suggest the best output format for those files and explain why.

3. Dry-run the savings. estimate_savings predicts the outcome without writing a single file.

Estimate how much I'd save converting them to WebP at quality 80.

4. Preview quality on one representative file. preview_settings compresses a single image at several quality levels so you can compare before committing a batch.

Show me /project/assets/hero.jpg at quality 60, 75, 85, and 95.

5. Run the batch, writing to a separate output directory. Never overwrite in place on the first run.

Compress everything in /project/assets to WebP at quality 80, max 1920px wide, save to /project/assets-optimized.

6. Verify with a report. compression_report gives you the aggregate and per-file numbers.

Generate a compression report comparing the two folders.

7. Undo if you don't like it. undo_last_batch clears the output directory so you can rerun with different settings. It requires explicit confirmation, so it won't fire accidentally.

The repository documents a real example of this flow: seven JPEGs converted to WebP at quality 80 went from 4.4 MB to 657 KB — an 85% reduction — from a single natural-language prompt.

---

8. Example Prompts That Work

Phrasing matters less than you'd expect, but being specific about paths, formats, and quality gets better results than being vague.

That last one is quietly useful. Photographs carry GPS coordinates, device serial numbers, and timestamps. Stripping them before sending files to a client or publishing them is a one-line request rather than a forgotten step.

---

9. Privacy and Why Local Matters Here

Every transformation runs through Pillow in a local Python process. No image bytes are sent anywhere. This isn't a policy commitment — it's an architectural fact you can verify by running the server with your network disconnected.

That matters more for agent-driven workflows than for manual ones, because the whole point of an agent is that you stop watching each step. If your tooling uploaded files to an API, you'd be authorizing a batch of uploads you never individually reviewed. Local processing removes the question.

Practical consequences:

• Client work under NDA can be processed without a third-party disclosure question.
• Screenshots of internal systems — dashboards, unreleased UI, customer records — never leave the machine.
• Photographs of identifiable people don't trigger data-processor obligations, because there's no processor.
• It works offline. On a plane, on a train, on a locked-down corporate network.

The same engine is available in the browser at compressfile.pro if you don't need agent integration — same client-side principle, no install.

---

10. Frequently Asked Questions

Do I need an API key? No. There's no account, no key, and no rate limit. The server runs locally and calls no external service.

Does it work with Cursor, or only Claude? Any MCP-compatible client. The config block is the same JSON; only its location differs between clients.

Why Python rather than Node? Pillow is the practical choice for image work in Python, and pillow-avif-plugin gives AVIF support without shelling out to a separate binary. The tradeoff is that you need a Python environment available.

Can it overwrite my originals? Only if you tell it to. The documented workflow writes to a separate output directory, and undo_last_batch requires an explicit confirm=True. Keep originals until you've checked the report.

How does duplicate detection work? Average hashing — a perceptual hash that produces similar fingerprints for visually similar images. It catches resized copies and re-encodes, not just byte-identical files. It can occasionally group images that are similar but not identical, so review before deleting.

Is this faster than a CLI script? For a job you'll run once, yes, because you skip writing the script. For a job that runs on every build, write the script — sharp or avifenc in your pipeline is the right tool. The agent covers the ad-hoc middle ground.

What if AVIF output fails? pillow-avif-plugin didn't install correctly, usually because the system libavif library is missing. Everything else keeps working; only AVIF output is affected.

---

The Short Version

1. MCP lets an AI assistant call local tools. mcp-compressfile exposes sixteen image tools to any MCP client.
2. Install is pip install "mcp[server]" Pillow pillow-avif-plugin imagehash, clone the repo, point your client at server.py.
3. Use the estimate → preview → compress → report sequence. Dry-run before writing, and always output to a separate directory.
4. EXIF auto-rotation and glob patterns are handled for you; JPEG output composites transparency onto white.
5. Everything runs locally through Pillow. Nothing is uploaded, and it works with the network off.

No AI integration needed? The same compression runs directly in your browser — no install, no upload.