immich-library-mcp

MCP server for an Immich photo library (built against Immich v3.3.3). It lets an agent search the library by content (CLIP smart search) or by metadata, read EXIF/people/album/tag detail, count and map the library, look at the photos themselves (preview/thumbnail images and numbered contact sheets returned as MCP image content), analyse it (duplicates, largest files, stacks, activity, processing queues), export browser-ready files plus a metadata manifest, stage originals on a shared mount for other MCP servers and, with a second key, organise it (favourites, ratings, descriptions, dates, locations, tags, albums, people, uploads, reprocessing).

Two keys, two trust levels:

• IMMICH_API_KEY (always): read-only. Scope it to read permissions only, so Immich itself refuses writes (the integration suite asserts a 403 on album create). With only this key the server is read-only: the curation tools are not registered at all, and the only writes are local files (the shared mount and the export folder).
• IMMICH_WRITE_API_KEY (optional): curation. Scoped to exactly the 13 write permissions the curation tools use and no read permissions, so every lookup still goes through the read key. It cannot delete or trash photos, share anything, or touch admin settings (the integration suite asserts 403s on /server/about, DELETE /assets and POST /shared-links). Give it only to clients that should organise the library; a shared HTTP deployment (chat front ends, automation) can run without it.

Install

uvx immich-library-mcp --stdio        # or: pip install immich-library-mcp

The distribution is immich-library-mcp (the name immich-mcp on PyPI belongs to another project); the import package is immich_mcp, and both immich-library-mcp and immich-mcp commands are installed. Claude Desktop / Claude Code (stdio):

{"mcpServers": {"immich": {"command": "uvx", "args": ["immich-library-mcp", "--stdio"],
  "env": {"IMMICH_URL": "http://localhost:2283", "IMMICH_API_KEY": "<read-only key>"}}}}

Tools

All tools take at least one parameter (Claude.ai's remote client rejects empty schemas). Every read tool carries readOnlyHint. The local file writers (immich_download, immich_export, immich_export_cleanup) and the curation tools don't; immich_export_cleanup, immich_delete_album, immich_delete_tag and immich_merge_people are marked destructiveHint (and prompt for confirmation through the fleet's MCP guard).

Reading

Library analysis (read)

immich_get_asset also returns Immich's per-asset key/value metadata, the stack it belongs to and its duplicate group.

Organising (only with IMMICH_WRITE_API_KEY)

Edits never modify original files: Immich keeps them in its database and an XMP sidecar. immich_upload only reads from the two hand-off folders (symlinks out of them are refused) and only accepts the extensions Immich lists in /server/media-types.

Names (people, albums, tags) resolve exact → case-insensitive → unique substring; ambiguous names error with the candidates. UUIDs pass through.

Times are the camera's local wall clock (Immich localDateTime); bare dates in filters are interpreted in TZ.

Gallery exports

immich_export writes into EXPORT_DIR/<folder> — a persistent, non-hidden folder (default ~/Pictures/Immich Exports, created at startup) that you can connect to another tool once and leave connected. Nothing sweeps it; prune with immich_export_cleanup(older_than_days=…). Because cleanup deletes inside it, EXPORT_DIR must be a dedicated folder: ~, ~/Pictures, ~/Desktop etc. are refused.

Where pixels come from. Immich renditions first: thumbnail/preview are Immich's own; fullsize follows Immich's redirect (the original for web formats, the preview where Immich has no full-size rendition). Local conversion (Pillow + pillow-heif) only fills the gaps: HEIC originals at fullsize/original are decoded and re-encoded locally. Camera RAW (ARW, NEF …) can't be decoded here, so it falls back to Immich's preview, flagged in that asset's note (turn on Immich's Full-size image generation for true full-res RAW). Re-encoded files keep the colour profile (iPhone Display P3) and EXIF orientation, and drop all other metadata, GPS included — safe to publish. keep files are untouched, so originals keep their EXIF.

Dedupe. If the folder's manifest already has the asset with the same settings and its file still matches the recorded sha256, it is skipped with no download (unchanged). Otherwise new bytes identical to the file on disk are not rewritten. A name clash with another asset, or with a file no manifest owns (your own edits), gets a -2 suffix rather than being overwritten. If a re-export renames an asset's file (new pattern or format), its old file is removed.

manifest.json is a JSON array, one entry per exported asset, sorted by capture time. It accumulates across runs (an asset re-exported replaces its entry):

{
  "asset_id": "a1b2c3d4-…", "file": "2009-12-02_0135_a1b2c3d4.jpg",
  "width": 1920, "height": 1440, "bytes": 285982, "sha256": "5f1d…",
  "taken": "2009-12-02T01:35:46", "place": "Kyoto, Japan", "city": "Kyoto",
  "country": "Japan", "camera": "Canon IXY DIGITAL 10", "people": ["…"],
  "immich_url": "https://photos.example.com/photos/a1b2c3d4-…",
  "type": "image", "duration_s": null, "variant": "preview/jpeg/0/q82"
}

Videos add video_file, video_bytes, video_sha256 when exported with include_video. variant records the export settings (for dedupe). immich_url is the plain web link; the API key never appears in any URL, filename or manifest.

The tool returns the absolute folder and manifest paths, count, total_bytes, by_status and per-asset {asset_id, status, file, note?, error?} with status exported | updated | unchanged | failed. Failures are per asset; the rest of the batch still exports. Downloads run 5 at a time, with at most 2 large decodes in parallel.

Configuration

Running

# stdio (interactive clients; no network surface, no bearer)
uvx --env-file .env immich-library-mcp --stdio

# Streamable HTTP at /mcp (stateless, bearer-authenticated)
MCP_BEARER_TOKEN=... IMMICH_API_KEY=... immich-mcp

# container
podman build -t immich-library-mcp .

Sync tool bodies run in a worker thread (one slow upstream call never stalls the event loop) and each call logs tool=X outcome=Y duration_ms=N to stderr. Argument values are never logged (httpx request logging is silenced because query strings carry names).

Testing

uv run --extra test pytest -q                       # tier 1 + 2 (mocked)
IMMICH_TEST=1 uv run --env-file .env \
    --extra test pytest tests/test_integration.py -v   # tier 3, live

The live curation tests run only when IMMICH_WRITE_API_KEY is in the env too. They change one real photo and one named person and restore every value in a finally (favourite, rating, description, a +60/−60 minute time shift, location), and create and delete their own album and tag. Merging people is never run live.

• tests/test_formatting.py — pure helpers (date bounds, rows, aggregation, name matching)
• tests/test_client.py — request shapes, errors, caching, streaming download
• tests/test_server.py — every tool through a mocked Immich, schema/annotation and bearer checks
• tests/test_library.py — the library-analysis tools (duplicates, large assets, random, stacks, activity, queues, folders, album, person)
• tests/test_curation.py — curation tools: request bodies, validation sends nothing, previous-value capture, upload path confinement, which key each request carries, registration only with the write key
• tests/test_export.py — HEIC/JPEG/WebP encoding (orientation, ICC kept, EXIF/GPS stripped), filename patterns, name claiming, manifest, cleanup, contact sheet
• tests/test_gallery.py — immich_export end to end against real image bytes and Immich's fullsize 302s: manifest schema, dedupe, HEIC/RAW paths, video, per-asset failures, collisions, cross-origin redirect refusal
• tests/test_integration.py — live: scope probes (403), search → detail → view, counts, places, download, HEIC + video export round trip, contact sheet, library analysis; with the write key, the restore-everything curation round trips