picture-mcp: The Hard Way

Build an MCP server that does everyday image jobs for an AI agent: look at a photo, shrink it to a size budget, strip the GPS before it is posted, and return a thumbnail so the agent can see what it just made. Pillow and nothing else. Every line explained, every claim checked by running real code on real images.

At the end you will have built a minimal version of picture-mcp yourself, and you will know the parts most image tutorials skip: the arithmetic of resizing, why alpha breaks JPEG conversion, how to search for a file size, what EXIF really contains and how to remove it without re-encoding, and how to let an agent near a filesystem safely.

Who This Is For

• Developers who built a "hello world" MCP server and want one that touches real files

• Anyone who has been bitten by a sideways photo, a black-background JPEG or a leaked GPS tag

• People who want to know what happens between "make it 200 KB" and the bytes on disk

Prerequisites: Python 3.10+. pip install -r requirements.txt (that is mcp and Pillow; no system packages, no ImageMagick, no ffmpeg).

Related MCP server: mcp-image-tools

Modules

Each module contains:

• README.md: the concepts and the design decisions

• main.py: a working, commented implementation that checks itself with assert

• break-it.md: challenges that break your own code, with hints

How To Use This Course

Option A: Build along. Read the modules in order, run each main.py, then do the break-it challenges.

Option B: Reference. Each main.py stands alone, with no imports between modules.

Option C: Use the finished tool. uvx picture-mcp is the full version of what Module 07 assembles.

Run It

pip install -r requirements.txt
python verify.py          # runs every module's main.py; each must exit 0
python verify.py 04 06    # just these
cd 07-mcp-wrapper-and-testing && python server.py --dir ~/Pictures   # the server itself

verify.py is what CI runs on Linux, macOS and Windows. The modules create their own test images (gradients, transparent logos, animated GIFs, EXIF with GPS) in a temp directory, so there are no fixtures to download.

License

MIT