Immich Photo Manager
MCP server and Claude Code plugin for intelligent photo management with self-hosted Immich.
Overview
When your Immich library has grown past what you can manage by hand, this plugin gives Claude direct access to your instance through 94 MCP tools and 13 skills. Search with natural language or by the text inside a photo, create geographic albums from GPS data, find duplicates across import sources, manage people and faces, repair metadata, cut frames out of videos, export an album as a PDF photobook, and browse results in interactive HTML galleries. The plugin runs on your machine and talks only to your Immich; originals never leave your server.
Key Features
- Natural language search: CLIP visual search ("sunset at the beach", "birthday cake"), plus people, places, dates and camera filters
- Text inside photos: OCR search finds a ticket, a sign or a document by what is written on it
- Geographic albums: albums organized by place from GPS clustering and temporal matching
- Duplicate detection: cross-source analysis with perceptual hashing (catches re-encoded copies from Apple Photos and Google Takeout); near-duplicates can be stacked instead of deleted
- People and faces: list, search, merge and rename people, reassign misidentified faces
- Metadata repair: fix noon and midnight timestamps, infer missing GPS from neighboring photos, correct timezone offsets
- Video frames and PDF reports: evenly spaced frames from any clip, and an album or selection exported as a PDF photobook with captions, built locally
- Dates in one call: month buckets, a calendar heatmap that shows gaps, and Immich's "on this day" memories
- Library health: asset inventory, metadata quality, storage breakdown and recommendations
- Notes between sessions: verdicts stored on each asset, so the next cleanup skips what an earlier pass reviewed
- Interactive galleries: self-contained HTML files with embedded thumbnails, 3 themes, 4 view modes, slideshow
- Safety first: findings are shown and confirmed before anything is written; trash first, permanent delete only on request
Compatibility
Every release runs live against real Immich 2.7.5 and 3.1.0 in Docker before it is tagged (all tools over MCP, state re-read after each write); the kit is in the repository under tests/live/. Works with Claude Code, Claude Desktop, LM Studio and any MCP client. Requires Immich 1.90+, an API key and Python 3.10+.
Installation
git clone https://github.com/drolosoft/immich-photo-manager.git
cd immich-photo-manager
pip3 install -r src/requirements.txt
claude plugin marketplace add ./
claude plugin install immich-photo-manager
Then run /setup-immich-photo-manager inside Claude Code, or say "Update my Immich credentials to https://photos.example.com with API key ". The same server is available as uvx immich-photo-manager for other MCP clients and as a Docker image (ghcr.io/drolosoft/immich-photo-manager, MCP over HTTP on port 8626).
Usage
"How healthy is my photo library?"
"Show me my photos from Italy"
"Find the photo with the train ticket"
"Create albums for everywhere I've traveled"
"Find duplicates in my library and keep the best of each group"
"Make me a PDF of the Sintra album"
/cleanup: scan for screenshots and junk
/my-travels: discover all travel destinations
Skills
photo-search, photo-cleanup, duplicate-report, auto-album-curator, album-manager, album-report, travel-map, metadata-fixer, storage-optimizer, library-health-report, people-report, rotate-photos, timeline-gaps.
Links
1---2name: immich-photo-manager3description: Manage your self-hosted Immich photo library through conversation: natural language and OCR search, geographic album curation, duplicate detection, people and faces, metadata repair, video frames and PDF photobooks. 94 MCP tools and 13 skills, tested live on Immich 2.x and 3.x. Install: claude plugin install immich-photo-manager4---5
6# Immich Photo Manager
7
8> MCP server and Claude Code plugin for intelligent photo management with self-hosted [Immich](https://immich.app).
9
10## Overview
11
12When your Immich library has grown past what you can manage by hand, this plugin gives Claude direct access to your instance through 94 MCP tools and 13 skills. Search with natural language or by the text inside a photo, create geographic albums from GPS data, find duplicates across import sources, manage people and faces, repair metadata, cut frames out of videos, export an album as a PDF photobook, and browse results in interactive HTML galleries. The plugin runs on your machine and talks only to your Immich; originals never leave your server.
13
14## Key Features
15
16- **Natural language search**: CLIP visual search ("sunset at the beach", "birthday cake"), plus people, places, dates and camera filters
17- **Text inside photos**: OCR search finds a ticket, a sign or a document by what is written on it
18- **Geographic albums**: albums organized by place from GPS clustering and temporal matching
19- **Duplicate detection**: cross-source analysis with perceptual hashing (catches re-encoded copies from Apple Photos and Google Takeout); near-duplicates can be stacked instead of deleted
20- **People and faces**: list, search, merge and rename people, reassign misidentified faces
21- **Metadata repair**: fix noon and midnight timestamps, infer missing GPS from neighboring photos, correct timezone offsets
22- **Video frames and PDF reports**: evenly spaced frames from any clip, and an album or selection exported as a PDF photobook with captions, built locally
23- **Dates in one call**: month buckets, a calendar heatmap that shows gaps, and Immich's "on this day" memories
24- **Library health**: asset inventory, metadata quality, storage breakdown and recommendations
25- **Notes between sessions**: verdicts stored on each asset, so the next cleanup skips what an earlier pass reviewed
26- **Interactive galleries**: self-contained HTML files with embedded thumbnails, 3 themes, 4 view modes, slideshow
27- **Safety first**: findings are shown and confirmed before anything is written; trash first, permanent delete only on request
28
29## Compatibility
30
31Every release runs live against real Immich 2.7.5 and 3.1.0 in Docker before it is tagged (all tools over MCP, state re-read after each write); the kit is in the repository under `tests/live/`. Works with Claude Code, Claude Desktop, LM Studio and any MCP client. Requires Immich 1.90+, an API key and Python 3.10+.
32
33## Installation
34
35```bash
36git clone https://github.com/drolosoft/immich-photo-manager.git
37cd immich-photo-manager
38pip3 install -r src/requirements.txt
39claude plugin marketplace add ./
40claude plugin install immich-photo-manager
41```
42
43Then run `/setup-immich-photo-manager` inside Claude Code, or say "Update my Immich credentials to https://photos.example.com with API key <key>". The same server is available as `uvx immich-photo-manager` for other MCP clients and as a Docker image (`ghcr.io/drolosoft/immich-photo-manager`, MCP over HTTP on port 8626).
44
45## Usage
46
47```
48"How healthy is my photo library?"
49"Show me my photos from Italy"
50"Find the photo with the train ticket"
51"Create albums for everywhere I've traveled"
52"Find duplicates in my library and keep the best of each group"
53"Make me a PDF of the Sintra album"
54/cleanup: scan for screenshots and junk
55/my-travels: discover all travel destinations
56```
57
58## Skills
59
60photo-search, photo-cleanup, duplicate-report, auto-album-curator, album-manager, album-report, travel-map, metadata-fixer, storage-optimizer, library-health-report, people-report, rotate-photos, timeline-gaps.
61
62## Links
63
64- **Repository**: https://github.com/drolosoft/immich-photo-manager
65- **Tools reference**: https://github.com/drolosoft/immich-photo-manager/blob/main/doc/MCP-TOOLS.md
66- **Demos from real sessions**: https://github.com/drolosoft/immich-photo-manager/blob/main/doc/demos/README.md
67- **Author**: [Drolosoft](https://drolosoft.com)
68- **License**: MIT
gabrielmoreira