Skip to main content
Glama
deenesjakoruzh
drolosoft

immich-photo-manager

by drolosoft
OverviewSchemaRelated ServersScoreDiscussions
Remote

📸🧹🗺️ MCP server for intelligent photo management with Immich — your self-hosted library, understood.

If you self-host Immich and your library has grown past the point where you can manage it by hand, immich-photo-manager gives Claude direct access to your Immich instance through 21 MCP tools and 11 specialized skills — from finding cross-ecosystem duplicates with perceptual hashing to generating interactive HTML galleries with a Cowork Actions Panel.

🚀 Quick Start

Prerequisites

Option A: Install as Claude Plugin (recommended)

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

# Register the marketplace and install
claude plugin marketplace add .
claude plugin install immich-photo-manager

Verify with claude plugin list.

That's it. Open Claude and say "how healthy is my photo library?" to get started.

Note: The plugin connects to your Immich MCP server at localhost:8626. Make sure the server is running before using the plugin. See Option B for how to build and start the server.

Option B: Manual MCP Server Setup

If you prefer to configure the MCP server manually instead of using the setup script:

git clone https://github.com/drolosoft/immich-photo-manager.git
cd immich-photo-manager
pip3 install -r src/requirements.txt

Create .mcp.json in the project root:

{
  "mcpServers": {
    "immich": {
      "command": "python3",
      "args": ["-m", "immich_mcp_server"],
      "env": {
        "PYTHONPATH": "/ABSOLUTE/PATH/TO/immich-photo-manager/src",
        "MCP_TRANSPORT": "stdio",
        "IMMICH_BASE_URL": "https://your-immich-server.com",
        "IMMICH_API_KEY": "your-api-key-here"
      }
    }
  }
}

Important: Use PYTHONPATH pointing to the src/ directory. Do NOT use cwd (it is silently ignored by Claude Code).

Note on Smart Search (CLIP): The search_smart tool requires the Immich machine learning service to be running and Smart Search enabled in Administration > Settings > Machine Learning Settings > Smart Search. If the ML service is not configured, the tool will return a helpful error message instead of failing silently. All other tools work without the ML service. See the Immich Smart Search docs for setup details.

🎬 Core Workflow

You: "Create albums for all the places I've traveled"

→ Scans GPS data from 28,000+ photos
→ Clusters by location, identifies 47 destinations across 14 countries
→ Proposes album list for approval
→ Creates albums with curated selections (20-50 photos each)
→ Publishes to Gallery with shared links

✅ Created: 🇮🇹 Roma, Italia (47 photos, Jun 2023)
✅ Created: 🇪🇬 Cairo & Luxor, Egypt (63 photos, Mar 2024)
✅ Created: 🇲🇽 Oaxaca, México (38 photos, Dec 2022)
... 44 more albums

Geographic album creation combines GPS coordinates, CLIP visual search, and temporal matching — then filters out screenshots and duplicates automatically. One request, dozens of curated albums.

✨ Features

Feature

What it does

🔍

AI-powered search

Natural language photo search via CLIP ("sunset at the beach", "birthday cake")

🗺️

Geographic albums

Create albums organized by place — GPS + CLIP combined for smart curation

🧹

Library cleanup

Detect screenshots, duplicates, and low-quality images with multi-signal analysis

🔎

Duplicate report

Deep cross-source duplicate analysis using perceptual hashing — finds re-encoded copies across Apple Photos, Google Photos, and other imports

🏥

Library health

Comprehensive health check — asset inventory, metadata quality, storage breakdown, and recommendations

📅

Timeline gaps

Find missing months, sparse periods, and single-source coverage risks in your photo timeline

🔧

Metadata fixer

Detect and repair broken dates (noon/midnight), missing GPS, wrong timezones — with neighbor interpolation

📌

Auto-album curator

Finds new photos that belong in existing albums using GPS, CLIP, and temporal matching

💾

Storage optimizer

Identify RAW+JPEG pairs, oversized videos, and other space hogs with reclaimable space estimates

👥

People report

Face recognition insights — who appears most, unnamed clusters worth naming, co-occurrence patterns

🌍

Travel map

Interactive Leaflet.js map with clustered pins showing every place you've photographed

🔗

Gallery publishing

Create shared links to make albums publicly accessible

🖼️

Interactive HTML galleries

Self-contained gallery pages with embedded thumbnails, 3 themes (light/system/dark), 4 view modes, slideshow, and keyboard navigation

🎛️

Cowork Actions Panel

Select photos in the gallery and copy batch commands (Create Album, Get EXIF, Find Similar, Download, etc.) straight into Cowork chat

🛡️

Safety first

Never deletes automatically — always shows findings and asks before acting

🖼️ Interactive Gallery & Cowork Actions

Say "show me photos from Barcelona" and the plugin generates a self-contained HTML gallery — no server required, opens in any browser.

You: "Show me my Egypt album"

→ Fetches album + base64 thumbnails from Immich
→ Generates single-file HTML with embedded images
→ 3 themes (light/system/dark), 4 view modes, slideshow, keyboard nav
→ Cowork Actions Panel for batch operations

✅ egypt-album.html — open it, browse your photos, select & act

The Cowork Actions Panel is a sticky toolbar inside each gallery. Select photos, then click any action — the command is copied to your clipboard, ready to paste into Cowork chat:

Action

What it copies

📋 Copy IDs

Raw asset IDs for scripting

➕ Create Album

"Create a new album with these photos: ..."

📂 Add to Album

"Add these photos to album [name]: ..."

📦 Move to Album

"Move these photos to a different album: ..."

🔍 Get EXIF Info

"Get EXIF metadata for these photos: ..."

🔎 Find Similar

"Find visually similar photos to: ..."

🖼️ Set as Cover

"Set this photo as the album cover: ..."

⬇️ Download

"Download these photos: ..."

❤️ Add to Favs

"Mark these photos as favorites: ..."

⚠️ Remove from Album

"Remove these from album [name]: ..."

🗑️ Delete Photos

"Delete these photos permanently: ..."

The gallery is fully responsive, works offline once generated, and supports touch gestures on mobile.

🤔 Why immich-photo-manager?

Immich is excellent at storing, viewing, and searching your photos. But managing a large library — deduplication, metadata repair, album curation, storage analysis — still requires manual effort or custom scripts. immich-photo-manager bridges that gap.

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

📊

Query database, build reports

Library health — one command for metadata quality, storage, recommendations

📅

SQL queries on timestamps

Timeline gaps — detects empty months and single-source coverage risks

🔧

EXIF tools, manual review

Metadata fixer — neighbor interpolation for missing GPS, broken timestamps

🛡️

Hope you don't delete the wrong thing

Safety first — never deletes without showing findings and asking

🧩 Skills

Skills are specialized workflows that combine MCP tools with domain knowledge. Each handles a specific photo management task end-to-end.

Skill

What it does

🗺️ Album Manager

Create and curate albums organized by geography — GPS + CLIP + filtering

🔍 Photo Search

Natural language search combining GPS, CLIP, and metadata filters

🧹 Photo Cleanup

Detect screenshots, duplicates, and low-quality images with confidence levels

🔎 Duplicate Report

Cross-source duplicate analysis using perceptual hashing (pHash)

🏥 Library Health

Asset inventory, metadata completeness, storage breakdown, recommendations

📅 Timeline Gaps

Detect empty months, sparse periods, single-source coverage risks

🔧 Metadata Fixer

Repair broken dates, missing GPS, wrong timezones with neighbor interpolation

📌 Auto-Album Curator

Find new photos that match existing albums using GPS, CLIP, and temporal patterns

💾 Storage Optimizer

Identify RAW+JPEG pairs, oversized videos, reclaimable space estimates

👥 People Report

Face recognition insights — top faces, unnamed clusters, co-occurrence patterns

🌍 Travel Map

Interactive Leaflet.js map with clustered pins and heatmap overlay

See the Skills Reference for detailed workflows, triggers, and output formats.

⚙️ How It Works

Claude ←→ MCP (stdio) ←→ Python Server ←→ Immich REST API
                                              your-instance

The MCP server is a Python module (immich_mcp_server) that communicates with Claude over stdio transport. It exposes 21 tools that map to Immich REST API endpoints, with added intelligence for batch operations, thumbnail embedding, and credential management.

Gallery HTML files are fully self-contained — thumbnails are fetched from Immich, encoded as base64, and embedded directly in the HTML. This is required because the Cowork viewer runs in an about: sandbox that blocks all external network requests. See Architecture for the full technical explanation.

21 MCP Tools

Category

Tools

🏥 Health (3)

ping, get_server_version, get_statistics

📷 Assets (2)

get_asset_info, get_map_markers

🔍 Search (2)

search_metadata, search_smart (CLIP)

📁 Albums (7)

list_albums, get_album, create_album, update_album, delete_album, add_assets_to_album, remove_assets_from_album

🔗 Sharing (2)

list_shared_links, create_shared_link

🖼️ Thumbnails (3)

get_asset_thumbnail, get_album_thumbnails, get_thumbnails_batch

🔧 Config (2)

get_connection_info, update_credentials

See the MCP Tools Reference for parameters, return types, and examples.

📚 Documentation

Document

Description

Getting Started

Installation, configuration, deployment options, and troubleshooting

Architecture

How base64-embedded thumbnails solve the Cowork sandbox restriction

Skills Reference

All 11 skills — workflows, triggers, parameters, output formats

MCP Tools Reference

All 21 MCP tools — parameters, return types, examples

CORS Setup Guide

Optional — enable direct URL thumbnail loading for browser-viewed galleries

Additional dependencies (optional)

Some advanced skills require Python packages or direct database access:

pip3 install Pillow imagehash pillow-heif

Package

Used by

Purpose

Pillow

duplicate-report

Image loading

imagehash

duplicate-report

Perceptual hashing (pHash)

pillow-heif

duplicate-report

HEIC/HEIF support (Apple Photos)

PostgreSQL client

library-health, timeline-gaps, people-report, storage-optimizer

Database-level analysis

🤝 Contributing

Contributions are welcome. If you find a bug, have a feature idea, or want to improve a skill:

  1. Fork the repository

  2. Create a feature branch (git checkout -b feature/my-feature)

  3. Commit your changes

  4. Open a pull request

For bug reports and feature requests, use GitHub Issues.

☕ 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

Install Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - A tier

How are these scores calculated?

Resources

Tools

View all tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/drolosoft/immich-photo-manager'

If you have feedback or need assistance with the MCP directory API, please join our Discord server