immich-photo-manager

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 Claude direct access to your instance — search, organize, deduplicate, and curate albums through natural conversation. Runs locally over MCP — your photos never leave your server.

---

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 as Claude Plugin (recommended)

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

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

That's it. Ask Claude: "how healthy is my photo library?"

For manual MCP server setup, see Getting Started.

Works in Claude Code

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

---

Highlights

• 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)
• 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.

---

Why immich-photo-manager?

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
🛡️	Manual review of every action	Safety first — shows findings, asks before acting

---

Documentation

Document	Description
Getting Started	Installation, manual MCP setup, deployment options, and troubleshooting
Skills Reference	All 11 skills — workflows, triggers, parameters, output formats
MCP Tools Reference	All 22 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

---

Contributing

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.

---

Support

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!

---

License

MIT License — free to use, modify, and distribute.

Forged by Drolosoft · Tools we wish existed