MCP server for intelligent photo management with Immich — your self-hosted library, understood.
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 — your photos never leave your server.
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.
- A running Immich instance (self-hosted, v1.90+)
- An Immich API key (how to create one)
- Python 3.10+ with
pip(download)
git clone https://github.com/drolosoft/immich-photo-manager.git
cd immich-photo-manager
claude plugin marketplace add .
claude plugin install immich-photo-managerThat's it. Ask Claude: "how healthy is my photo library?"
For manual MCP server setup, see Getting Started.
The same plugin runs in Claude Code — search your library, curate albums, and generate galleries right from the terminal.
Full conversation transcript: Claude Code demo
immich-photo-manager is an MCP server — it works with any AI assistant that speaks the Model Context Protocol, not just Claude.
============================================================
IMMICH-PHOTO-MANAGER × GEMMA 4 (LM STUDIO)
============================================================
Immich: https://your-immich-server.com
Model: gemma4-26b-it (local, LM Studio)
Query: "Show me my Lanzarote albums"
1. Getting MCP tool schemas...
38 MCP tools available
2. Asking Gemma 4...
Gemma 4 chose: list_albums({})
3. Executing 'list_albums' against Immich...
Found 124 total albums, 14 Lanzarote albums:
- Lanzarote Amarillo (26 photos)
- Lanzarote Rojo (201 photos)
- Lanzarote Azul (187 photos)
- Lanzarote Marrón (208 photos)
- Lanzarote Negro (193 photos)
- Lanzarote Verde (201 photos)
- Lanzarote Gasolina (174 photos)
...
4. Gemma 4 interpreting results...
"I found 14 Lanzarote albums — 7 color-themed with
1,190 photos and 7 location-specific albums."
RESULT: Zero cloud dependency — fully self-hosted stack.
| Client | Status |
|---|---|
| Claude Code | Tested |
| Claude Desktop | Tested |
| LM Studio (Gemma 4) | Tested |
| Cursor, Windsurf, VS Code, Cline, Zed | Compatible (MCP stdio) |
Full transcript: Gemma 4 demo · Test script:
test-lmstudio-mcp.py
- AI-powered search — natural language photo search via CLIP ("sunset at the beach", "birthday cake")
- Geographic albums — create albums organized by place, combining GPS + CLIP + temporal matching
- Metadata repair — fix noon/midnight timestamps, infer missing GPS from neighboring photos, correct timezone offsets
- Library cleanup — detect screenshots, duplicates, and low-quality images with multi-signal analysis
- Duplicate detection — cross-source analysis using perceptual hashing (finds re-encoded copies across Apple Photos, Google Photos, and other imports)
- Bulk rotation — rotate entire albums or selections at once (90°/180°/270°); non-destructive, accumulates across calls, one-click revert
- People & face management — list, search, merge, and organize recognized people; reassign misidentified faces; view face thumbnails
- Trash & asset lifecycle — safely delete assets to trash, permanently remove, restore from trash; complete asset lifecycle management
- Library health — one command for asset inventory, metadata quality, storage breakdown, and recommendations
- Interactive galleries — self-contained HTML pages with embedded thumbnails, 3 themes, 4 view modes, and a Cowork Actions Panel for batch operations
Select photos in the gallery, click an action, and paste the command into Claude. See Skills Reference for all 11 skills.
Immich is excellent at storing and viewing your photos. But managing a large library — deduplication, metadata repair, album curation, storage analysis — still requires manual effort or custom scripts.
| Manual / scripts | immich-photo-manager | |
|---|---|---|
| 🔍 | Write API calls, parse JSON | Natural language — "find my sunset photos from Italy" |
| 🗺️ | Export GPS, cluster manually | Geographic albums — automatic GPS + CLIP + temporal matching |
| 🧹 | Hash files, diff checksums | Perceptual hashing — finds re-encoded duplicates across import sources |
| 🔧 | Edit EXIF one file at a time | Metadata repair — batch-fix timestamps, infer GPS, correct timezones |
| 📊 | Query database, build reports | Library health — one command for metadata quality, storage, recommendations |
| 🔄 | Rotate one photo at a time | Bulk rotation — rotate entire albums at once, non-destructive |
| 🛡️ | Manual review of every action | Safety first — shows findings, asks before acting |
| Document | Description |
|---|---|
| Getting Started | Installation, manual MCP setup, deployment options, and troubleshooting |
| Skills Reference | All 12 skills — workflows, triggers, parameters, output formats |
| MCP Tools Reference | All 38 MCP tools — parameters, return types, examples |
| Architecture | How base64-embedded thumbnails solve the Cowork sandbox restriction |
| CORS Setup Guide | Optional — enable direct URL thumbnail loading for browser-viewed galleries |
Contributions are welcome — bug fixes, new skills, feature ideas. Open an issue or submit a PR.
If immich-photo-manager helps manage your library, consider giving it a star on GitHub — it helps others discover the project.
If immich-photo-manager saved you time or made your photo library easier to manage, consider buying me a coffee — it keeps the next one coming!
MIT License — free to use, modify, and distribute.
Forged by Drolosoft · Tools we wish existed