Immich Photo Manager

immich-photo-manager

MCP server for intelligent photo management with [Immich](https://immich.app): 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)

git clone https://github.com/drolosoft/immich-photo-manager.git

cd immich-photo-manager pip3 install -r src/requirements.txt # the plugin runs on your system python3

claude plugin marketplace add ./ claude plugin install immich-photo-manager

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:

/setup-immich-photo-manager

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):

Update my Immich credentials to http://immich.local:2283 with API key <your API key>

Either way the credentials are saved for every session from then on; repeat to change server or key. Confirm any time with:

What Immich version am I connected to?

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:

cd immich-photo-manager && git pull      # the clone you installed from

claude plugin marketplace update drolosoft-marketplace claude plugin update immich-photo-manager@drolosoft-marketplace

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.

A PDF report follows the same rule: export_pdf writes the file to disk on the machine running the server, and it is not sent anywhere unless you pass return_base64=true. The file goes where output_path says (default your Desktop); existing files are never overwritten. Frames that only go into the PDF never leave your machine and cost no tokens; only the frames you ask the model to look at do. When the assets carry GPS, the Places page draws a map with tiles from tile.openstreetmap.org, the only third-party call the server itself makes; pass map=false to skip it and keep everything inside your network.

What the plugin runs, sends and fetches

• Runs: one local process, the MCP server, started as python3 on a file inside the plugin (src/plugin_entry.py). There are no hooks and no background jobs, and nothing is downloaded or installed when it starts. The Python libraries are the ones you install yourself from src/requirements.txt.
• Your Immich server: every tool is a call to the public API of the Immich server you configure, with your API key in the x-api-key header. upload_asset sends a local file you name to that server.
• Other servers, from the plugin: only tile.openstreetmap.org, and only when a PDF report draws its Places map. The request carries the tile coordinates of the area, so it tells that server roughly where the photos were taken. map=false skips it.
• Other servers, from the pages it writes: gallery pages load nothing from outside; their handwriting font is embedded in the page. The travel map, served from your own machine, loads Leaflet and two of its add-ons from unpkg.com, each pinned to one version with an integrity hash so the browser refuses a changed file, and its map tiles from OpenStreetMap, which shows those two servers the areas you look at. Thumbnails are embedded in the page, or loaded from your own Immich when you set up CORS.
• Files on your machine: export_pdf and download_archive write where you say and never overwrite. Galleries and maps are HTML files written by the assistant. The duplicate report can read an import folder on disk to compare photos, and it removes files there only when you approve the exact list.
• Credentials: entered in the plugin's configuration dialog, the API key is kept in your system's secure storage. Given in conversation (/setup-immich-photo-manager or update_credentials), the key passes through the model like any other message and is saved in two files only your user can read: config.json in the plugin's cache folder and ~/.immich-photo-manager/config.json.
• Public links: create_shared_link makes a link that anyone with the URL can open. It is created only when you ask for sharing; list_shared_links shows the ones that exist and delete_shared_link removes one.
• Deleting: delete_assets moves assets to Immich's trash, which restore_assets undoes. It deletes for good only with force=true, and empty_trash is permanent too. The cleanup and duplicate skills show what they found and wait for your answer before they delete anything. The plugin never changes Claude's permission settings.

Connect, check, switch: all by talking

You never edit config files after setup. The connection is managed in conversation:

One connection at a time: to work with a second Immich (a test instance, a friend's server), say the *update* sentence again; say it once more to go back. Wrong URL or key? It tells you, and keeps the previous connection.

Try the full walkthrough: [Demo 11, Album Walkthrough](doc/demos/11-album-walkthrough.md). Read an album item by item, find who repeats, create a sub-album, tag and describe every photo.

Works in Claude Code

The same plugin runs in [Claude Code](https://docs.anthropic.com/en/docs/claude-code): search your library, curate albums, and generate galleries right from the terminal.

![Split scr