drolosoft/immich-photo-manager

> **MCP server for intelligent photo management with Immich: your self-hosted library, understood.**
> An unofficial community plugin by Drolosoft. It is not affiliated with, sponsored by or endorsed by Immich or FUTO; "Immich" is their name and is used here only to say which server the plugin works with. It talks to your Immich server through its public API.
If your Immich library has grown past what you can manage by hand, **immich-photo-manager** gives any AI assistant direct access to your instance: search, organize, deduplicate, and curate albums through natural conversation. Works with Claude, Gemma, or any MCP-compatible client. Runs locally and talks only to your Immich; your originals stay on your server (see what leaves your network).
> **Tested, not assumed.** Every push runs 364 unit tests on CI. Every release is also run **live against real Immich 2.7.5 and 3.1.0** (Docker, all 94 tools over the MCP protocol's legacy era, state re-read after each write) before it is tagged; both protocol eras (the legacy handshake and stateless 2026-07-28) are pinned on every push by SDK-free wire tests (tests/test_raw_wire_eras.py). The kit is in tests/live/, reproducible by anyone. The demos in doc/demos/ are transcripts of real sessions, Demo 11 is this exact flow prompt by prompt, and Demo 12 runs the video frames and PDF photobook on a real clip. Demos 13 to 18 cover everything added in 2.x (library discovery, OCR and people search, memories and stacks, partners and downloads, asset notes, the Docker image) from real sessions. Details: How it's tested.
---
What It Does
Say **"create albums for all my trips"** and watch it work:
GPS coordinates, CLIP visual search, and temporal matching, combined in one request to create dozens of curated albums. No scripts, no manual sorting.
---
Quick Start
Prerequisites
- A running Immich instance (self-hosted, v1.90+)
- An Immich API key (how to create one)
- **Python 3.10+** with pip (download)
Install (Claude Code plugin)
The install prints that two options are not set yet: the server URL and the API key. Inside a session, /plugin asks for them in a dialog (the key goes to your system's secure storage); from the shell you can pass them with --config immich_base_url=... --config immich_api_key=..., or leave both empty and let the setup below save them.
Open Claude Code (restart it if it was already open) and connect it to your Immich. Guided:
It asks for your server URL and API key, checks them against the server, saves them, and shows your library numbers:
Or skip the guide and say it in one line (same thing underneath):
Either way the credentials are saved for every session from then on; repeat to change server or key. Confirm any time with:
That's the whole install. Claude Desktop, Cowork or another MCP client instead of Claude Code? That is the plain MCP server without the skills: see Getting Started, route B.
Update the plugin
One line, no reinstall:
Then restart Claude Code. drolosoft-marketplace is the name the marketplace gets when you add it from the clone (claude plugin marketplace list shows it). Your saved credentials carry over.
After pulling a new version, run pip3 install -r src/requirements.txt again: 1.7.1 added the video (av) and PDF (fpdf2) libraries to the plugin's dependencies. On the uvx route, uvx --refresh immich-photo-manager --help once, then restart the client.
Upgrading from 2.0.12
Nothing to set up again. The options, the server command and the tool names are the same as in 2.0.12, and saved credentials carry over. What changes:
- The recommended place for the server URL and the API key is the plugin's configuration dialog (/plugin, then the plugin's options), which keeps the key in your system's secure storage. If you connected through /setup-immich-photo-manager, that keeps working and you do not have to move anything.
- The images in the repository were saved again without colour profiles or EXIF data. They look the same.
- The README now lists everything the plugin runs, sends and fetches in one place.
What leaves your network
The plugin process runs on your machine and only talks to your Immich. But everything the assistant *reads* through it goes to the model you use: filenames, dates, EXIF, album lists, and, when you ask it to look at pictures, thumbnails (250px by default, 1440px previews on request). Originals are never fetched. With Claude that means those thumbnails leave your network; with a local model over MCP (LM Studio, Ollama) nothing does. Nothing is sent unless you ask for it: listing albums or fixing dates moves text only, "tell me what's in these photos" moves images.