MCP SERVERSearch, curate, deduplicate and repair a self-hosted Immich photo library by talking to it.
LABSCO SUMMARY
Immich stores and shows photos well; what it does not do is curate. This closes that gap by combining the searches — CLIP visual, GPS, EXIF and date — inside one request, so "make albums for all my trips" becomes an operation rather than a script you would have to write first. Deletions go to trash by default and rotation is non-destructive with a one-call revert, which is what makes it reasonable to let an assistant work in bulk.
A client for a self-hosted Immich instance. It searches the library by metadata or by what a photo looks like, curates albums, manages recognised people, repairs metadata and handles the trash — running on your machine and talking only to your Immich.
A running Immich instance, v1.90 or newer, and an API key from it. Python 3.10 or newer. Point a client at uvx immich-photo-manager with IMMICH_BASE_URL and IMMICH_API_KEY, or install it as a Claude plugin from the repository, which runs its own setup script. Speaks stdio by default; MCP_TRANSPORT=http turns it into a Streamable HTTP service. Uploads are capped at 25MB and to jpg, jpeg, png, heic, mp4 and mov. Duplicate detection needs Immich's ML service. Originals are never fetched, but everything the assistant reads goes to whichever model you use — filenames, dates, EXIF, album lists, and, when you ask it to look at pictures, thumbnails at 250px by default or 1440px previews on request.
One command plus a key — uvx immich-photo-manager, then supply credentials
USE CASES
Search visually in plain language, then pull thumbnails of the hits to confirm you have the right ones.
Search by place and date range, create the album from those results, then add whatever the first pass missed.
Review the detected duplicate groups, then resolve each by choosing which copy stays.
Name the unnamed clusters, merge the ones that are the same person, and move a face that landed on the wrong one.
Correct the original date, the GPS coordinates and the description on the assets that came in wrong.
Create a shared link for the album with download and metadata settings, then set an expiry or revoke it later.
Restore specific assets from trash, or everything at once, before anyone empties it.
Rotate a whole album without touching the originals, and revert in one call if you overshoot.
Create the tags, apply them in bulk across search results, and take them off just as cleanly.
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
add_assets_to_albumAdd existing assets to an album. Use this to curate albums from search results or other asset lists. Assets can belong to multiple albums simultaneously. Side effect: modifies album membership.
Args: album_id: Target album UUID. asset_ids: List of asset UUIDs to add to the album.
Returns: JSON with album_id, count added, and per-asset success/error details.
create_albumCreate a new album, optionally pre-populated with assets. Use this to organize photos into collections. Side effect: creates a new album in Immich.
Args: name: Album display name (e.g. 'Roma, Italia', 'Birthday 2024'). description: Optional album description text. asset_ids: Optional list of asset UUIDs to add immediately on creation.
Returns: JSON with the new album's id, name, and asset count.
create_shared_linkCreate a public shared link for an album, making it accessible via URL without authentication. Use this to publish a gallery for external viewing. Side effect: creates a publicly accessible URL.
Args: album_id: The album UUID to share publicly. allow_download: Allow visitors to download original files (default true). show_metadata: Show EXIF data to visitors (default true). description: Optional human-readable description for the link.
Returns: JSON with link id, key, album_id, and the full shareable URL.
create_tagCreate a new tag for categorizing assets. Use list_tags first to avoid duplicates. Side effect: creates a new tag in Immich.
Args: name: Tag display name (e.g. 'Vacation', 'Family', 'Work'). Must be unique. color: Optional hex color for the tag (e.g. '#FF5733').
Returns: JSON with the new tag's id, name, and color.
delete_albumDelete an album container. The photos inside are NOT deleted — they remain in the library. Use this to remove unwanted album groupings. Side effect: permanently deletes the album (cannot be undone).
Args: album_id: The album's UUID to delete.
Returns: JSON with deleted confirmation and album_id.
delete_assetsDelete assets (soft-delete to trash or permanent). Use this to remove unwanted photos/videos. Default is soft-delete (recoverable via restore_assets). With force=true, deletion is PERMANENT and IRREVERSIBLE. Side effect: moves/deletes assets.
Args: asset_ids: List of asset UUIDs to delete. force: false (default) = move to trash (recoverable). true = PERMANENTLY delete (no undo).
Returns: JSON with count deleted and whether force was used.
delete_shared_linkDelete (revoke) a shared link, making the public URL immediately inaccessible. The album and its photos are unaffected. Side effect: permanently removes the link.
Args: link_id: The shared link's UUID to delete.
Returns: JSON with deleted confirmation and link_id.
delete_tagDelete a tag and remove it from all assets. The assets themselves are unaffected. Side effect: permanently deletes the tag (cannot be undone).
Args: tag_id: The tag's UUID to delete.
Returns: JSON with deleted confirmation and tag_id.
empty_trashPermanently delete ALL assets currently in trash. DESTRUCTIVE and IRREVERSIBLE. Use this only after confirming the user wants to purge all trashed items. For deleting specific assets, use delete_assets instead. Side effect: permanently destroys all trashed assets and frees storage.
Returns: JSON with success confirmation.
get_albumGet full details for a specific album including all its asset IDs. Use this to inspect album contents or retrieve asset IDs for further operations (thumbnails, metadata, rotation). For listing all albums, use list_albums instead. Read-only.
Args: album_id: The album's UUID (from list_albums or create_album).
Returns: JSON with album metadata and a flat list of all asset_ids in the album.
get_album_thumbnailsGet base64-encoded thumbnails for photos in an album. Use this to generate visual HTML galleries from an existing album. For thumbnails from search results (no album), use get_thumbnails_batch instead. Read-only.
Args: album_id: The album's UUID. size: 'thumbnail' (250px) or 'preview' (1440px). Default: 'thumbnail'. limit: Max thumbnails to return (1-50, default 20).
Returns: JSON with album info and thumbnails array (each with asset_id, base64 data, filename, date).
get_asset_facesGet all detected faces in a photo with their person assignments. Use this to see who is in a specific photo or to find face IDs for reassign_face. Read-only.
Args: asset_id: The asset's UUID.
Returns: JSON array of face detections (each with face_id, person_id, person_name, bounding box).
get_asset_infoGet full metadata for a single asset. Use this when you need EXIF details, GPS coordinates, camera info, or file properties for a known asset ID. For finding assets, use search_metadata or search_smart instead. Read-only.
Args: asset_id: The asset's UUID (from search results, album listings, or list_assets).
Returns: JSON with EXIF data, GPS, dates, dimensions, file size, camera make/model, and owner.
get_asset_thumbnailGet a base64-encoded thumbnail image for a single asset. Use this to visually inspect one photo. For multiple photos, use get_thumbnails_batch (by IDs) or get_album_thumbnails (by album). Read-only.
Args: asset_id: The asset's UUID. size: 'thumbnail' (250px, fast) or 'preview' (1440px, higher quality). Default: 'thumbnail'.
Returns: JSON with 'data' (base64 string) and 'type' (MIME type, e.g. 'image/jpeg').
get_connection_infoReturn the Immich base URL and a masked API key. Use this to populate gallery template placeholders (e.g. {{IMMICH_URL}}). The API key is intentionally masked for security — thumbnails use base64 data URIs, not direct API calls. Read-only.
Returns: JSON with base_url and api_key_masked (first 8 + last 4 chars only).
get_duplicatesGet all ML-detected duplicate asset groups. Use this to review potential duplicates before resolving them with resolve_duplicates. Requires Immich ML service. Read-only.
Returns: JSON array of duplicate groups (each with duplicateId, assets array, and similarity scores).
get_map_markersGet GPS map markers for all geotagged assets. Use this to discover where photos were taken or to build travel maps. For searching by city/country name, use search_metadata instead. Read-only. Returns up to 500 markers.
Args: file_created_after: ISO date lower bound (e.g. '2023-01-01'). file_created_before: ISO date upper bound. is_favorite: If true, only return favorites.
Returns: JSON with total count and markers array (each with asset ID, lat, lon).
get_personGet full details for a specific person including name, birth date, and photo count. Use this after finding a person via list_people or search_people. Read-only.
Args: person_id: The person's UUID (from list_people or search_people).
Returns: JSON with person details (id, name, birthDate, isHidden, photoCount, thumbnailPath).
get_person_thumbnailGet a base64-encoded face crop thumbnail for a person. Use this to visually identify a person before merging or renaming. Read-only.
Args: person_id: The person's UUID.
Returns: JSON with 'data' (base64 string of face crop) and 'type' (MIME type).
get_server_versionGet the Immich server version. Use this to check compatibility or report the running server version. Read-only.
Returns: JSON with major, minor, and patch version numbers.
get_shared_linkGet full details of a shared link including permissions, expiry, and linked assets. Use this to inspect a specific link's configuration. Read-only.
Args: link_id: The shared link's UUID (from list_shared_links).
Returns: JSON with link details, permissions, expiry date, and associated assets/album.
get_statisticsGet library statistics. Use this for a quick overview of library size without listing individual assets. Read-only.
Returns: JSON with total photo count, video count, and storage usage in bytes.
get_tagGet details for a specific tag. Use this to inspect a tag's properties. Read-only.
Args: tag_id: The tag's UUID (from list_tags).
Returns: JSON with tag id, name, color, and usage count.
get_thumbnails_batchGet base64-encoded thumbnails for arbitrary asset IDs without needing an album. Use this to visually display search results or any ad-hoc set of photos. For album-based thumbnails, use get_album_thumbnails. For a single photo, use get_asset_thumbnail. Read-only.
Args: asset_ids: List of asset UUIDs to fetch thumbnails for. size: 'thumbnail' (250px) or 'preview' (1440px). Default: 'thumbnail'. limit: Max thumbnails to return (1-50, default 20). Only the first N IDs are fetched.
Returns: JSON with thumbnails array (each with asset_id, base64 data, filename, date).
list_albumsList all albums in the library with summary info. Use this to discover existing albums before creating new ones or to find an album ID. Read-only.
Args: shared: true = only shared albums, false = only non-shared, omit = all albums.
Returns: JSON with total count and albums array (each with id, name, description, assetCount, shared status).
list_assetsList assets with simple filters (no search query needed). Use this to browse the library by status (favorites, archived, trashed) or type. For finding specific content, use search_metadata (structured) or search_smart (visual AI). Read-only.
Args: is_favorite: true = only favorites, false = only non-favorites, omit = all. is_archived: true = only archived, false = only non-archived, omit = all. is_trashed: true = only trashed items, false = only active, omit = all. asset_type: 'IMAGE' or 'VIDEO'. Omit for both. page: Page number, starting from 1 (default 1). size: Results per page (1-200, default 50).
Returns: JSON with total count, current page, and assets array with IDs, filenames, dates, and types.
list_peopleList all recognized people (face clusters) in the library. Use this to browse who appears in the photo library or find a person's ID. For searching by name, use search_people instead. Read-only.
Args: page: Page number, starting from 1 (default 1). size: Results per page (default 50). with_hidden: Include people marked as hidden (default false).
Returns: JSON with total count, page, and people array (each with id, name, thumbnailPath, photoCount).
list_shared_linksList all shared links (public gallery URLs). Use this to see what's currently shared publicly or to find a link ID for updates/deletion. Read-only.
Returns: JSON with total count and links array (each with id, key, type, description, album info).
list_tagsList all tags in the library. Use this to discover existing tags before creating new ones or to find a tag ID for tagging operations. Read-only.
Returns: JSON with total count and tags array (each with id, name, color).
merge_peopleMerge multiple person clusters into one. Use this when the same real person has been split into multiple face clusters. DESTRUCTIVE and IRREVERSIBLE: merged persons are permanently deleted and all their faces transfer to the target.
Args: person_id: The target person UUID to keep (receives all merged faces). merge_ids: List of person UUIDs to absorb into the target. These persons are permanently deleted.
Returns: JSON with merge result details.
pingCheck Immich server connectivity. Use this to verify the server is reachable before running other operations. Read-only.
Returns: JSON with 'server' status ('pong' if healthy).
reassign_faceReassign a detected face to a different person. Use this to correct face recognition mistakes (e.g. a face wrongly attributed to Person A should be Person B). Get face_id from get_asset_faces first. Side effect: permanently changes face-to-person mapping.
Args: face_id: The face detection UUID (from get_asset_faces results). person_id: The correct person UUID to assign this face to.
Returns: JSON with the updated face assignment.
remove_assets_from_albumRemove assets from an album without deleting them. The photos remain in the library and other albums. Use this to un-curate mistakenly added assets. Side effect: modifies album membership.
Args: album_id: Album UUID to remove assets from. asset_ids: List of asset UUIDs to remove from this album.
Returns: JSON with album_id, count removed, and per-asset result details.
resolve_duplicatesResolve duplicate groups by choosing which assets to keep and which to trash. Use this after reviewing results from get_duplicates. Trashed assets can still be recovered via restore_assets. Side effect: moves rejected duplicates to trash.
Args: groups: List of dicts, each with: duplicateId (from get_duplicates), assetIds (UUIDs to KEEP), trashIds (UUIDs to TRASH).
Returns: JSON with count of resolved groups.
restore_assetsRestore specific assets from trash back to the active library. Use this to selectively recover accidentally deleted photos. For restoring everything at once, use restore_trash instead. Side effect: moves specified assets out of trash.
Args: asset_ids: List of asset UUIDs currently in trash to restore.
Returns: JSON with count of restored assets.
restore_trashRestore ALL trashed assets back to the library. Use this to undo an accidental bulk deletion. For restoring specific assets only, use restore_assets instead. Side effect: moves all trashed assets back to the active library.
Returns: JSON with success confirmation.
revert_asset_editsRemove all non-destructive edits (rotation, crop, mirror) from assets, restoring original appearance. Use this to undo rotate_assets or any other display transforms. Provide EITHER asset_ids OR album_id. Side effect: deletes all edit records for the assets.
Args: asset_ids: List of asset UUIDs to revert. Mutually exclusive with album_id. album_id: Revert all assets in this album. Mutually exclusive with asset_ids.
Returns: JSON with reverted/failed counts.
rotate_assetsApply a non-destructive clockwise rotation to one or more assets. Use this to fix orientation issues. The original file is never modified — rotation is a display transform only. Use revert_asset_edits to undo. Provide EITHER asset_ids OR album_id. Side effect: writes rotation edits to Immich; accumulates with existing rotation.
Args: angle: Clockwise degrees, must be a multiple of 90 (90, 180, or 270). Default: 90. asset_ids: List of asset UUIDs to rotate. Mutually exclusive with album_id. album_id: Rotate all assets in this album. Mutually exclusive with asset_ids.
Returns: JSON with rotated/failed counts and the applied angle.
search_metadataSearch assets by EXIF metadata fields. Use this when you know specific criteria like city, camera model, or date range. For natural language visual queries (e.g. 'sunset at the beach'), use search_smart instead. For browsing without criteria, use list_assets. Read-only.
Args: city: City name from EXIF GPS reverse-geocoding (case-sensitive, e.g. 'Barcelona'). state: State or region name. country: Country name (e.g. 'Spain', 'Egypt'). make: Camera manufacturer (e.g. 'Apple', 'Canon', 'Sony'). model: Camera model string (e.g. 'iPhone 14 Pro', 'EOS R5'). taken_after: ISO date — return only assets captured after this date. taken_before: ISO date — return only assets captured before this date. is_favorite: If true, only return favorites. asset_type: 'IMAGE' or 'VIDEO'. Omit for both. page: Page number, starting from 1 (default 1). size: Results per page (1-200, default 50).
Returns: JSON with total match count, current page, and assets array with IDs, filenames, and dates.
search_peopleSearch for people by name (partial match). Use this when you know the person's name. For browsing all people, use list_people instead. Read-only.
Args: name: Full or partial name to match (case-insensitive). with_hidden: Include hidden people in results (default false).
Returns: JSON array of matching people with id, name, and photo count.
search_smartAI-powered visual search using CLIP embeddings. Use this when describing what a photo looks like in natural language (e.g. 'sunset at the beach', 'dog playing fetch'). For structured criteria (city, camera, date), use search_metadata instead. Requires Immich ML service with Smart Search enabled. Read-only.
Args: query: Natural language description of the visual content to find. city: Optional city filter to narrow results geographically. state: Optional state/region filter. country: Optional country filter. taken_after: ISO date — only assets captured after this date. taken_before: ISO date — only assets captured before this date. page: Page number, starting from 1 (default 1). size: Results per page (1-200, default 50).
Returns: JSON with total count, page, and assets ranked by visual similarity to the query.
tag_assetsApply a tag to multiple assets at once. Use this to bulk-categorize photos (e.g. tag all vacation photos). Side effect: adds tag association to assets.
Args: tag_id: The tag UUID to apply (from list_tags or create_tag). asset_ids: List of asset UUIDs to tag. Must not be empty.
Returns: JSON with tag_id, count tagged, and per-asset results.
untag_assetsRemove a tag from multiple assets. The tag itself remains; only the association is removed. Side effect: removes tag-to-asset links.
Args: tag_id: The tag UUID to remove from assets. asset_ids: List of asset UUIDs to untag. Must not be empty.
Returns: JSON with tag_id, count untagged, and per-asset results.
update_albumUpdate an album's name or description. Use this to rename or re-describe an existing album. Side effect: modifies album metadata in Immich.
Args: album_id: The album's UUID. name: New album name. Leave empty to keep current name. description: New description. Leave empty to keep current description.
Returns: JSON with the updated album object.
update_asset_metadataUpdate metadata fields on a specific asset. Use this to fix dates, correct GPS, add descriptions, or change favorite/rating status. Only provided fields are modified. Side effect: permanently changes asset metadata in Immich.
Args: asset_id: The asset's UUID. date_time_original: ISO 8601 datetime (e.g. '2019-07-14T15:23:41.000Z'). latitude: GPS latitude, decimal degrees (-90.0 to 90.0). longitude: GPS longitude, decimal degrees (-180.0 to 180.0). description: Free-text description/caption for the asset. is_favorite: Set favorite status (true/false). rating: Star rating (1-5), or null to clear.
Returns: JSON with the updated asset object.
update_credentialsUpdate the Immich connection credentials. Use this when the API key has been rotated or the server URL changed. Validates credentials before applying. Side effect: persists new credentials to disk and hot-swaps the live connection.
Args: base_url: Full Immich server URL including protocol (e.g. 'https://photos.example.com'). api_key: A valid Immich API key (generated in Immich > User Settings > API Keys).
Returns: JSON with success status, photo/video counts confirming access, and persistence path.
update_personUpdate a person's profile details. Use this to name unnamed faces, set birth dates, hide clutter faces, or change the representative thumbnail. Only provided fields are modified. Side effect: changes person metadata in Immich.
Args: person_id: The person's UUID. name: Display name (e.g. 'John Smith'). Set to name unnamed face clusters. birth_date: ISO date (e.g. '1990-05-15'). is_hidden: Hide from the People view (useful for strangers/clutter). is_favorite: Mark as a favorite person. feature_face_asset_id: Asset UUID whose face crop becomes the person's thumbnail. color: Hex color label for UI grouping.
Returns: JSON with the updated person object.
update_shared_linkUpdate a shared link's permissions or expiry. Use this to tighten/loosen access or set an expiration date. Side effect: changes public link behavior immediately.
Args: link_id: The shared link's UUID. allow_download: Allow visitors to download original files. show_metadata: Show EXIF data to visitors. allow_upload: Allow visitors to upload photos to the shared album. description: Link description. Empty string clears it. expiry_at: ISO 8601 expiry datetime. Empty string removes expiry (link never expires).
Returns: JSON with the updated shared link object.
update_tagUpdate a tag's name or color. Side effect: changes apply to all assets using this tag.
Args: tag_id: The tag's UUID. name: New tag name. Omit to keep current. color: New hex color (e.g. '#FF5733'). Omit to keep current.
Returns: JSON with the updated tag object.
upload_assetUpload a local photo or video file to Immich. Use this to ingest new media into the library. Constraints: max 25MB, allowed types: jpg, jpeg, png, heic, mp4, mov, gif, webp. Symlinks are rejected for security. The original file is NOT modified or deleted. Side effect: creates a new asset in Immich.
Args: file_path: Absolute path to the local file (e.g. '/tmp/photo.jpg'). Must exist. album_id: Optional album UUID to add the uploaded asset to immediately.
Returns: JSON with new asset id, filename, size_mb, and album assignment status if applicable.
BEFORE YOU INSTALL
50 tools when we connected; the project documents 53. The three missing are image-block variants of the thumbnail tools: get_asset_image, get_album_images and get_images_batch. No setting is documented; they suit clients that render images inline, which likely decides whether they appear.
INSTALLATION
uvx immich-photo-managerClone the repository, install the plugin's Python dependencies (it runs on your system python3), and install the plugin from the clone:
git clone https://github.com/drolosoft/immich-photo-manager.git
cd immich-photo-manager
pip3 install -r src/requirements.txt
claude plugin marketplace add ./
claude plugin install immich-photo-managerOpen Claude Code (restart it if it was already open) and run /setup-immich-photo-manager. It asks for your Immich server URL and API key, checks them against the server, and saves them.
{
"mcpServers": {
"immich": {
"command": "uvx",
"args": [
"immich-photo-manager"
],
"env": {
"IMMICH_BASE_URL": "<YOUR_IMMICH_BASE_URL>",
"IMMICH_API_KEY": "<YOUR_IMMICH_API_KEY>"
}
}
}
}Run the server as a container. It serves MCP over Streamable HTTP on port 8626:
docker run -d -p 8626:8626 \
-e IMMICH_BASE_URL=<YOUR_IMMICH_BASE_URL> \
-e IMMICH_API_KEY=<YOUR_IMMICH_API_KEY> \
-v ./exports:/data \
ghcr.io/drolosoft/immich-photo-managerIn Open WebUI, open Tools → Integrations (or Workspace / Tools / MCP, depending on your version) and add an MCP server: Type MCP Streamable HTTP, ID immich, URL http://localhost:8626/mcp. If Open WebUI reaches the container under another address, use that address and add it to the container with -e MCP_ALLOWED_HOSTS=<YOUR_MCP_ALLOWED_HOSTS>
MCP servers
savethepolarbears
aaronsb
box-community