Immich Photo Manager
AI-powered photo management for Immich
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.
The Solution
Tell Claude what you want in plain English. The MCP server handles everything — smart search via CLIP, automatic geographic albums, assisted cleanup of screenshots and duplicates. It never deletes without asking.
Why immich-photo-manager?
Managing a large photo library shouldn't require writing scripts. This MCP server turns natural language into intelligent library management.
| 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 |
| 🔒 | 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 — dark/light theme, 4 view modes, full-screen slideshow, touch gestures, lazy loading. Opens in any browser, works offline.
19 MCP Tools
Complete library management: health checks, asset info, metadata search, album CRUD, shared links, thumbnails, and album updates.
Safety First
Never deletes automatically. Always shows findings and asks for confirmation. Your photos are safe.
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.
Architecture
Immich Photo Manager is a Go server that speaks the Model Context Protocol (MCP) via Streamable HTTP. Claude connects to it, and it translates requests into Immich REST API calls.
19 tools organized in 6 categories: Health (3), Assets (2), Search (2), Albums (8), Sharing (3), and Thumbnails (2). Each tool maps directly to Immich API endpoints with added intelligence for curation and filtering.
Quick Start
Get connected to your Immich instance in under two minutes.
Then add it to your Claude configuration (.mcp.json):
Specialized Skills
Pre-built workflows that combine multiple MCP tools into multi-step operations. One natural language request triggers the full 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 |
/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: frequency, unnamed clusters, co-occurrence |
19 MCP Tools
Complete Immich library management organized in 6 categories. Each tool maps directly to Immich API endpoints with added intelligence.
| Category | Tools |
|---|---|
| Health | ping, get_server_version, get_statistics |
| Assets | get_asset_info, get_map_markers |
| Search | search_metadata, search_smart (CLIP) |
| Albums | list_albums, get_album, create_album, update_album, delete_album, add_assets_to_album, remove_assets_from_album |
| Sharing | list_shared_links, create_shared_link, delete_shared_link |
| Thumbnails | get_album_thumbnails, get_asset_thumbnail |
Also available as an installable Cowork plugin for Claude Desktop. Drop in immich-photo-manager.plugin and get 5 pre-built slash commands: /immich-status, /create-album, /cleanup, /my-travels, /photo-search. No terminal, no configuration files — just install and go.
Requirements
A running Immich instance and a Claude client — that's all you need.
| Requirement | Detail |
|---|---|
| Immich | v1.90+ |
| Go | 1.24+ |
| macOS / Linux | Go binary, no native dependencies |
| Claude | Claude Desktop (Cowork) or Claude Code CLI |
Built With
A single Go binary with minimal dependencies. No runtime requirements beyond a running Immich instance.
- Go 1.24+ — Fast compilation, single binary output
- mcp-go v0.32.0 — Model Context Protocol SDK
- Immich REST API — Full library management
- CLIP embeddings — Natural language photo search via Immich's ML
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 to use with your Immich instance.