Immich Photo Manager
AI photo management for Immich, 94 tools, Immich 2.x and 3.x
The Problem
You have thousands of photos in Immich but finding anything means scrolling endlessly. Search is limited to basic metadata. Creating albums is manual and tedious. Screenshots, duplicates, and blurry photos clutter your library. A total mess.
The Solution
Tell Claude what you want in plain English. The MCP server does the rest: smart search via CLIP and the text inside photos, automatic geographic albums, assisted cleanup that remembers every verdict, frames from any video and a PDF photobook. It never deletes without asking.
Why immich-photo-manager?
Managing a large photo library should not require writing scripts. This MCP server turns natural language into library management, and it is tested rather than assumed: 349 unit tests on every push, and every release run live against real Immich 2.7.5 and 3.1.0 with 132 checks that re-read the server after each write.
| Manual / Scripts | immich-photo-manager | |
|---|---|---|
| 🔍 | Write API calls, parse JSON | Natural language queries |
| 🌎 | Export GPS, cluster manually | GPS + CLIP + automatic temporal matching |
| 🗑 | Hash files, diff checksums | Perceptual hashing across imports |
| 📊 | Query database, build reports | One-command comprehensive assessment |
| 📅 | SQL queries on timestamps | Automatic gap detection and risk analysis |
| 🔄 | Rotate photos one at a time | Bulk rotate entire albums at once |
| 📄 | Grep filenames and hope | Text inside photos (OCR), people, places |
| 🎬 | One poster thumbnail per video | Frames of any moment, contact sheets, PDF photobook |
| 📝 | Redo the review every session | The plugin remembers every verdict and its reason |
| 🔒 | Risk of deletion errors | Safety-first with approval workflows |
Features
Smart Search
Search your photos with natural language via CLIP embeddings. "Sunset at the beach" finds exactly what you'd expect.
Geographic Albums
Automatically organize photos by location using GPS data and CLIP. Curated albums with 20-50 photos per place.
Library Cleanup
Detect screenshots, duplicates, and low-quality photos with multi-signal analysis. Review before any action is taken.
Interactive HTML Galleries
Say 'show me photos from Barcelona' and get a self-contained HTML gallery: 3 themes (light/system/dark), 4 view modes, full-screen slideshow, touch gestures, lazy loading. Opens in any browser, works offline.
94 MCP Tools
The whole Immich API worth having: search, albums, people, tags, sharing, trash, duplicates, memories, stacks, partners, comments, downloads, timeline and notes. Every tool runs live against Immich 2.7.5 and 3.1.0 before a release ships.
Safety First
Never deletes automatically. Always shows findings and asks for confirmation. Your photos are safe.
Bulk Rotation
Select wrongly-rotated photos, toss them in an album, and rotate the whole batch at once. Non-destructive, accumulates across calls, and reverts with one command.
Cowork Actions Panel
Select photos in any gallery, click an action, and the formatted command is copied to your clipboard, ready to paste into Cowork. 11 color-coded actions from Create Album to Delete.
Video Frames and PDF Photobooks
Claude watches a video frame by frame, skims a long clip as a contact sheet, and builds a PDF photobook on your machine: one full page per chosen moment, captions, cover, index and a map. Photos at original quality.
Know the Library First
One call reports what the server can do (OCR, smart search, faces, version). Then places, cameras, a month by month map, a per-day heatmap and a random sample, all without downloading a single photo.
Memories, Stacks, Partners
On-this-day memories, stacks that group forty takes of the same shot behind one cover without deleting any, family sharing between accounts, comments on shared albums, and the album as a zip.
A Memory of Every Review
Verdicts and reasons are stored on each asset, next to the photo they describe. A later session skips what was already reviewed instead of paying for the analysis twice. Tags stay the visible state in Immich; notes carry the why.
Architecture
Immich Photo Manager is a Python server that speaks the Model Context Protocol, over stdio or HTTP, in both protocol eras (the legacy handshake and the stateless 2026-07-28 spec). A client connects to it, and it translates requests into Immich REST API calls for 2.x and 3.x alike.
94 tools in 21 categories: Health (4), Assets (9), Search (9), Albums (7), Sharing (5), Thumbnails (3), Images (3), Video (2), Export (2), Config (2), People (8), Trash (4), Duplicates (2), Tags (7), Memories (4), Timeline (3), Stacks (5), Partners (5), Activities (3), Download (2) and Notes (5).
Quick Start
Three ways in: uvx from PyPI, the Claude Code plugin with its 13 skills, or the Docker image. Connected in under two minutes.
Install with uvx (recommended)
Available on PyPI. No repo cloning, no PYTHONPATH.
Install as a Claude Code plugin
The route with the 13 skills and the slash commands. Then /setup-immich-photo-manager asks for the URL and API key and saves them.
As a Docker container
Official multi-arch image (amd64 and arm64). Serves MCP over HTTP on port 8626, both protocol eras, plus /health for the healthcheck. PDFs and zips land in /data.
Manual Setup
Then add it to your Claude configuration (.mcp.json):
Specialized Skills
Thirteen workflows that combine several MCP tools into one request, installed with the Claude Code plugin. One sentence triggers the whole pipeline.
| Skill | Description |
|---|---|
/immich-status | Check server health, photo/video counts, and storage usage |
/create-album | Create curated geographic albums with 20-50 photos per location |
/cleanup | Multi-signal detection of screenshots, duplicates and low-quality photos, with stacks as the gentler option and notes that remember every decision |
/my-travels | Generate travel albums from GPS data across your entire library |
/duplicate-report | Deep cross-source duplicate analysis using perceptual hashing |
/library-health | Asset inventory, metadata quality, storage breakdown, and recommendations |
/timeline-gaps | Identify missing months, sparse periods, and coverage risks |
/metadata-fixer | Repair broken dates, missing GPS, wrong timezones via neighbor interpolation |
/auto-album-curator | Find new photos matching existing albums via GPS, CLIP, and temporal patterns |
/storage-optimizer | Identify RAW+JPEG pairs, oversized videos, and space-hogging files |
/people-report | Face recognition insights: who appears most, unnamed clusters, first and last appearance, merges that preview names before acting |
/rotate-photos | Bulk rotate entire albums or selections: non-destructive, accumulates, one-click revert |
/album-report | Turn an album or a selection into a PDF: cover, index, places map, one page per photo or per chosen video moment |
94 MCP Tools
Complete Immich library management in 21 categories. Each tool maps to an Immich API endpoint that exists on both 2.x and 3.x; version differences are handled inside the plugin.
| Category | Tools |
|---|---|
| Health (4) | ping, get_server_version, get_capabilities, get_statistics |
| Assets (9) | get_asset_info, reverse_geocode, update_asset_metadata, update_assets_metadata, rotate_assets, revert_asset_edits, get_map_markers, upload_asset, list_assets |
| Search (9) | search_metadata, search_smart (CLIP), search_explore, search_cities, search_places, search_suggestions, search_random, search_statistics, search_large_assets |
| Albums (7) | list_albums, get_album, create_album, update_album, delete_album, add_assets_to_album, remove_assets_from_album |
| Sharing (5) | list_shared_links, create_shared_link, get_shared_link, update_shared_link, delete_shared_link |
| Thumbnails (3) | get_asset_thumbnail, get_album_thumbnails, get_thumbnails_batch |
| Images (3) | get_asset_image, get_album_images, get_images_batch |
| Video (2) | get_video_frames, get_video_frames_json |
| Export (2) | get_export_preview, export_pdf |
| Config (2) | get_connection_info, update_credentials |
| People (8) | list_people, get_person, update_person, merge_people, search_people, get_person_thumbnail, get_asset_faces, reassign_face |
| Trash (4) | delete_assets, empty_trash, restore_trash, restore_assets |
| Duplicates (2) | get_duplicates, resolve_duplicates |
| Tags (7) | list_tags, get_tag, create_tag, update_tag, delete_tag, tag_assets, untag_assets |
| Memories (4) | list_memories, create_memory, update_memory, delete_memory |
| Timeline (3) | get_timeline_buckets, get_timeline_bucket, get_calendar_heatmap |
| Stacks (5) | create_stack, list_stacks, get_stack, update_stack, delete_stack |
| Partners (5) | list_users, list_partners, create_partner, update_partner, remove_partner |
| Activities (3) | list_activities, create_activity, delete_activity |
| Download (2) | get_download_info, download_archive |
| Notes (5) | review_assets, record_action, get_asset_notes, get_assets_notes, clear_asset_notes |
Install it as a Claude Code plugin and you get the 13 skills plus five slash commands: /setup-immich-photo-manager, /immich-status, /create-album, /cleanup, /my-travels. Credentials are set by talking and survive plugin updates. Claude Desktop, Cowork and other clients use the plain server through uvx or Docker.
Requirements
A running Immich instance and an MCP client. That is all.
| Requirement | Detail |
|---|---|
| Immich | 2.x and 3.x, run live against 2.7.5 and 3.1.0 before every release |
| Python | 3.10+ |
| Install | uvx immich-photo-manager (PyPI), claude plugin install or docker run ghcr.io/drolosoft/immich-photo-manager |
| macOS / Linux | Python server; video and PDF ship as wheels, no system ffmpeg |
| MCP Clients | Claude Desktop, Claude Code, Cursor, Windsurf, LM Studio, any MCP client, both protocol eras (2025 and 2026-07-28) |
Built With
A Python server with a short dependency list. Video frames and PDFs ship as wheels, so there is nothing to compile and no system ffmpeg to install.
- Python 3.10+ — Async server, lightweight and portable
- mcp (Python SDK v2): Model Context Protocol over stdio or HTTP, both protocol eras
- Immich REST API: full library management on 2.x and 3.x
- CLIP embeddings — Natural language photo search via Immich's ML
- PyAV and fpdf2: frames cut from any video, PDF photobooks built on your machine
- Docker: multi-arch image on GitHub Container Registry, published with every release
I build tools I wish existed, then give them away.
If one of them saved you time, a coffee keeps the next one coming.
Ready to organize your photos?
Immich Photo Manager is free, open source, and ready for your Immich instance: PyPI, Claude Code plugin or Docker.