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 handles everything — smart search via CLIP, automatic geographic albums, assisted cleanup of screenshots and duplicates. It never deletes without asking. A total pleasure.

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
🔄	Rotate photos one at a time	Bulk rotate entire albums at once
🔒	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.

🛠

50 MCP Tools

Complete library management: health checks, metadata search, album CRUD, bulk rotation, tags & organization, asset upload, people & face management, trash lifecycle, duplicate detection, shared links, and visual thumbnails.

🔒

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.

Architecture

Immich Photo Manager is a Python server that speaks the Model Context Protocol (MCP) via stdio. Claude connects to it, and it translates requests into Immich REST API calls.

# Data flow

Claude  <-->  MCP (stdio)  <-->  Python Server  <-->  Immich REST API
                                                      your-instance

50 tools organized in 10 categories: Health (3), Assets (7), Search (2), Albums (7), Sharing (5), Thumbnails (3), Config (2), People & Faces (8), Trash (4), Duplicates (2), and Tags (7).

Quick Start

Get connected to your Immich instance in under two minutes.

Install with uvx (recommended)

Available on PyPI. No repo cloning, no PYTHONPATH.

{
  "mcpServers": {
    "immich": {
      "command": "uvx",
      "args": ["immich-photo-manager"],
      "env": {
        "IMMICH_BASE_URL": "https://your-immich-instance.com",
        "IMMICH_API_KEY": "your-api-key"
      }
    }
  }
}

Install as Claude Plugin

git clone https://github.com/drolosoft/immich-photo-manager.git
cd immich-photo-manager
claude plugin marketplace add .
claude plugin install immich-photo-manager

Manual Setup

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

Then add it to your Claude configuration (.mcp.json):

{
  "mcpServers": {
    "immich": {
      "command": "python3",
      "args": ["-m", "immich_mcp_server"],
      "cwd": "/path/to/immich-photo-manager",
      "env": {
        "PYTHONPATH": "./src",
        "IMMICH_BASE_URL": "https://your-immich-instance.com",
        "IMMICH_API_KEY": "your-api-key"
      }
    }
  }
}

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
`/rotate-photos`	Bulk rotate entire albums or selections — non-destructive, accumulates, one-click revert

50 MCP Tools

Complete Immich library management organized in 10 categories. Each tool maps directly to an Immich API endpoint.

Category	Tools
Health	`ping`, `get_server_version`, `get_statistics`
Assets	`get_asset_info`, `update_asset_metadata`, `rotate_assets`, `revert_asset_edits`, `get_map_markers`, `upload_asset`, `list_assets`
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`, `get_shared_link`, `update_shared_link`, `delete_shared_link`
Thumbnails	`get_album_thumbnails`, `get_asset_thumbnail`, `get_thumbnails_batch`
Config	`get_connection_info`, `update_credentials`
People	`list_people`, `get_person`, `update_person`, `merge_people`, `search_people`, `get_person_thumbnail`, `get_asset_faces`, `reassign_face`
Trash	`delete_assets`, `empty_trash`, `restore_trash`, `restore_assets`
Duplicates	`get_duplicates`, `resolve_duplicates`
Tags	`list_tags`, `get_tag`, `create_tag`, `update_tag`, `delete_tag`, `tag_assets`, `untag_assets`

Cowork Plugin

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. Requires Python 3.10+ and pip3 install mcp httpx.

Requirements

A running Immich instance and a Claude client — that's all you need.

Requirement	Detail
Immich	v1.90+
Python	3.10+
Install	`uvx immich-photo-manager` (PyPI) or `claude plugin install`
macOS / Linux	Python server, no native dependencies
MCP Clients	Claude Desktop, Claude Code, Cursor, Windsurf, LM Studio, any MCP client

Built With

A lightweight Python server with minimal dependencies. No runtime requirements beyond Python 3.10+ and a running Immich instance.

Python 3.10+ — Async server, lightweight and portable
mcp (Python SDK) — Model Context Protocol via stdio
Immich REST API — Full library management
CLIP embeddings — Natural language photo search via Immich's ML

Star on GitHub

I build tools I wish existed, then give them away.
If one of them saved you time, a coffee keeps the next one coming.

The Problem

The Solution

Why immich-photo-manager?

Features

Smart Search

Geographic Albums

Library Cleanup

Interactive HTML Galleries

50 MCP Tools

Safety First

Bulk Rotation

Cowork Actions Panel

Architecture

Quick Start

Install with uvx (recommended)

Install as Claude Plugin

Manual Setup

Specialized Skills

50 MCP Tools

Cowork Plugin

Requirements

Built With

Ready to organize your photos?