Immich Photo Manager

Add 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.

Forget the plugin's notes on assets (reviews and actions). Only the plugin's own key is removed; metadata other apps stored stays. Side effect: deletes the notes on the server. Args: asset_ids: The assets to clear. Returns: JSON with success, how many assets were cleared, and a failed array of {asset_id, error}. Success is true only when nothing failed.

Post a comment (or a like) on a shared album or on one asset in it. Side effect: the activity appears for everyone the album is shared with. Args: album_id: The album to comment on. comment: The comment text. Leave empty when sending a like. asset_id: Attach the comment/like to this asset instead of the album. like: True to send a like instead of a comment. Returns: JSON with the created activity's id and type.

Create 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 an "on this day" memory from chosen assets. Use this after curating a set of photos from the same past date (e.g. via search_metadata with a date range) to make them show up in Immich's memories feed. Side effect: creates a memory on the server. Args: memory_at: ISO date the memory is shown on (usually today's month and day). year: The past year the memory looks back to (required by Immich). asset_ids: Assets to include. May be empty, but an empty memory shows nothing. Returns: JSON with the created memory's id, type, memory_at, the year it remembers, is_saved, asset_count and a trimmed assets list (id, filename, date).

Share this account's library with another user on the server. The other user will see these photos next to their own. Find the id with list_users. Side effect: grants the user read access to the whole library. Args: user_id: The user to share with. Returns: JSON with the new partner entry.

Create 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.

Group near-identical assets (a burst, retries of the same shot) into one stack. The library then shows the stack as a single item fronted by its primary asset, which keeps every shot without the visual clutter — a gentler cleanup than deleting. The first id becomes the primary. Side effect: creates the stack on the server. Args: asset_ids: The assets to group, at least two. Order matters: the first is the cover. Returns: JSON with the new stack's id, primary_asset_id and asset list.

Create 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.

Remove one comment or like. Side effect: deletes it for everyone. Args: activity_id: The activity to remove (from list_activities). Returns: JSON confirming the deletion.

Delete 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 success, the deleted album's id and album_id.

Delete 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 a memory. The photos stay in the library — only the memory entry goes away. Side effect: removes the memory from the server. Args: memory_id: The memory to delete. Returns: JSON confirming the deletion.

Delete (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.

Dissolve a stack. The assets are NOT deleted — they simply show as individual items again. Side effect: removes the grouping on the server. Args: stack_id: The stack to dissolve. Returns: JSON confirming the deletion.

Delete 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 success, the deleted tag's id and tag_id.

Download an album or a selection as one zip of the original files, written to a local path. Use get_download_info first when the size matters. The file is streamed to disk (safe for big albums) and an existing file is never overwritten. Side effect: writes a file on the machine running the server. Args: output_path: Where to write the zip (an existing file is refused). album_id: Download the whole album. asset_ids: Or download just these assets. Returns: JSON with path, bytes written and how many assets went in, or an error.

Permanently 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.

Build a PDF (cover, index, places, one section per asset) from an album or a list of assets, on the machine running this server. Immich metadata (date, place, camera, people, tags) is always included; pass `captions` {asset_id: text} with what you saw to add your analysis. Video frames go straight into the PDF and cost no tokens (up to 120 per video). The PDF never enters the conversation unless return_base64=True. If the user asked for a PDF without saying how they want it, call get_export_preview first and ask them about the choices it lists. Keep the selection coherent: one story per PDF. Never mix unrelated assets (two videos about different things, photos from different events) just to show more; if the user's material spans several stories, offer one PDF per story instead. Args: album_id: Album UUID, or asset_ids: explicit asset UUIDs (exactly one of the two). output_path: Where to write (default ~/Desktop/<title>.pdf). Existing files are never overwritten. title: Cover title (default: album name or "Immich export <date>"). captions: {asset_id: text} written after looking at the images. layout: 'detail' (one asset per page with its data, default), 'grid' (six per page) or 'photobook' (one asset per page, image as large as it fits, caption under it; a video with several chosen frames unfolds into one full page per frame). frames_per_video: Frames per video, evenly spaced (0-120, default 4; 0 = poster only). frame_interval: One frame every N seconds instead of frames_per_video (same 120 cap). frame_times: {asset_id: [seconds, ...]} exact moments for specific videos, chosen after looking at their frames ("the representative frame"). Wins over frames_per_video/frame_interval for the listed videos; others keep the spread. frame_captions: {asset_id: [text, ...]} one caption per extracted frame, in frame order (photobook prints each on its frame's page; other layouts ignore them). image_size: 'original' (default): photos go in at the stored file's quality, re-encoded to at most 3000px (a format the server cannot decode, like some HEIC, falls back to preview with a note); 'preview' (1440px) or 'thumbnail' for smaller files. frame_size: video frame size in the PDF: 'auto' (default, same as 'preview': quality is free inside the PDF) or 'thumbnail' for a smaller file. language: 'en' (default) or 'es' for the fixed labels on the pages (Index, Places, Camera, page numbers); captions stay in whatever language you wrote. map: Draw an OpenStreetMap map on the Places page when assets carry GPS (default True; tiles come from tile.openstreetmap.org, the only third-party call this server makes — pass map=False to skip it). cover, index, places: Include each front-matter page (all default True; turn them off for a print-ready photobook of bare pages). footer: 'full' (plugin name, server and page number, default), 'pages' (just the page number) or 'none'. header: Repeat the title at the top of every page except the cover (default False). videos_position: Where the video pages (frame strips or frame pages) go: 'mixed' with the photos in the general order (default), 'first' or 'last'. order: 'auto' (albums read oldest to newest, like the frames inside a video; asset_ids keep the order you passed), 'oldest', 'newest' or 'given'. confirm: Only asked for when explicit asset_ids mix videos more than 90 days apart (different stories). Pass True only when the user themselves asked to mix them; exporting a whole album never needs it. limit: Max assets (1-500, default 100). return_base64: Also return the PDF bytes (skipped above 2 MB; every MB is roughly 350k tokens in the conversation). Returns: JSON {path, pages, bytes, assets_included, assets_skipped:[{id, reason}], warnings:[...]}.

Get 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, a flat list of all asset_ids, and an assets array (id, filename, type, date, recognized people) so "who appears in this album / who repeats" can be answered without further calls.

Get an album's thumbnails as image blocks for inline visual display. Use this to visually browse an album in clients that render images. For HTML gallery generation with base64 data URIs (Cowork/skills), use get_album_thumbnails instead — it returns JSON with filenames and dates. 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: A list of image blocks suitable for visual display.

Get 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 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 a single asset's thumbnail as an image block for inline visual display. Use this in clients that render images (Open WebUI, Claude Desktop). For HTML gallery generation with base64 data URIs (Cowork/skills), use get_asset_thumbnail instead — it returns JSON. Read-only. Args: asset_id: The asset's UUID. size: 'thumbnail' (250px, fast) or 'preview' (1440px, higher quality). Default: 'thumbnail'. Returns: An image block (MCP ImageContent) for visual display.

Get 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). with_notes: Also include the plugin's notes on the asset (past review verdicts and recorded actions, see get_asset_notes). One extra request. Returns: JSON with EXIF data, GPS, dates, dimensions, file size, camera make/model, and owner; plus a `notes` object (reviews and actions) when with_notes is true.

The plugin's notes on one asset: past review verdicts with reasons and recorded actions, newest last. Empty lists when it was never annotated. Read-only. Args: asset_id: The asset to read. Returns: JSON with asset_id, reviews [{at, verdict, reason}] and actions [{at, action, detail}].

Get 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').

Which of these assets already carry notes, and their last verdict — the call that lets a cleanup pass skip what an earlier session reviewed. Immich cannot search this metadata, so the server is asked once per asset (no tokens spent on the ones without notes). Read-only. Args: asset_ids: The candidates to check (an album's assets, a search result). Returns: JSON with checked (how many were asked), annotated (one compact row per asset that has notes — asset_id, last_verdict, last_reason, last_review_at, and the reviews/actions counts) and a failed array of {asset_id, error} for the assets that could not be read. Success is true only when nothing failed.

How many photos per day, over a date range — the data behind a calendar heatmap. Use this to find gaps (months with nothing), busy periods, or to check a library's health at a glance without listing assets. Immich 3.x answers natively; on Immich 2.x the same shape is built from the timeline (taken dates only), which costs one request per month in the range, so pass the narrowest range that answers the question. Read-only. Args: from_date: ISO date lower bound (e.g. '2026-01-01'). Omit for the server default on Immich 3.x; on 2.x an omitted bound means the last 365 days, because an open-ended range would walk every month of the library. to_date: ISO date upper bound. Omit for the server default. heatmap_type: 'Taken' (capture date, default) or 'Upload' (when it reached Immich; 3.x only). Returns: JSON with source ('immich' or 'timeline'), total and a series of {date, count} for the days that have activity, oldest first (a day missing from the series had nothing).

What this Immich server can do: version, feature flags and known quirks. Use this once at the start of a session to learn whether OCR, smart search or facial recognition are available before offering them, and which behaviours differ between Immich 2.x and 3.x. Read-only. Returns: JSON with server_version, immich_major, features (the server's own flags: ocr, smartSearch, facialRecognition, map, trash...) and quirks (plain sentences about version-specific behaviour the caller should know). When the API key may not read the feature flags, features is empty and a note says so; the version and the quirks still come back.

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

How big the zip of an album or selection would be, BEFORE building it. Use this to warn the user about the size (originals and videos add up fast) and then decide whether to call download_archive. Read-only. Args: album_id: Size the whole album. asset_ids: Or size just these assets. Returns: JSON with total_size_mb, asset_count and the number of archives Immich would split the download into.

Get ML-detected duplicate asset groups (same image stored more than once). Use this to review potential duplicates before resolving them with resolve_duplicates. Requires Immich ML service. Note: "duplicates" means the same picture, not the same person — for people use get_album (assets[].people) or get_asset_faces. Read-only. Args: album_id: Optional. Restrict to groups that touch this album; each group then also reports which of its assets are inside/outside the album. Returns: JSON array of duplicate groups (each with duplicateId, assets array, and similarity scores).

List what export_pdf would include (id, type, filename, date, place, people, video duration) so you know which assets exist before looking at images and writing captions. Pass exactly one of album_id / asset_ids. Read-only. The result also carries `options`: every choice export_pdf accepts, with its default. When the user asked for a PDF without saying how they want it, show them these choices and ask (layout, cover pages, which video moments, captions) before exporting; when they did give specs, or just want "a PDF, defaults are fine", export directly. Args: album_id: Album UUID, or asset_ids: Explicit asset UUIDs (search results, a selection). limit: Max assets (1-500, default 100). Returns: JSON {title, count, assets:[...], warnings:[...]} or {"error": ...}.

Get thumbnails for arbitrary asset IDs as image blocks for inline visual display. Use this to visually show search results in clients that render images. For HTML gallery generation with base64 data URIs (Cowork/skills), use get_thumbnails_batch instead — it returns JSON with filenames and dates. 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: A list of image blocks suitable for visual display.

Get 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 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 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 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 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.

One stack with its assets. Use this after list_stacks to see everything a group holds before changing its cover or dissolving it, or to check what create_stack actually grouped. Read-only. Args: stack_id: The stack to fetch. Returns: JSON with id, primary_asset_id and the asset list.

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

The assets of one month bucket from get_timeline_buckets. Use the two tools together to walk a library month by month without expensive searches. Read-only. Args: time_bucket: The bucket key exactly as get_timeline_buckets returned it (e.g. '2026-03-01'). album_id: Only assets in this album. person_id: Only assets showing this person. tag_id: Only assets carrying this tag. is_favorite: If true, only favorites. Returns: JSON with an assets array; each row has asset_id, date, is_image, is_favorite, duration, city and country.

Month-by-month map of the library: one bucket per month with its asset count. Use this before fetching assets — it shows in one cheap call which months hold photos and how many, ideal for finding gaps, busy periods, or navigating a large library without paging through everything. Read-only. Args: album_id: Only count assets in this album. person_id: Only count assets showing this person. tag_id: Only count assets carrying this tag. is_favorite: If true, only count favorites. order: 'desc' for newest month first (the default), 'asc' for oldest first. Returns: JSON with total_buckets and a buckets array of {timeBucket, count}, newest month first unless order='asc'.

Get frames of a video as image blocks, to "watch" a clip. Immich keeps one poster per video; this downloads the video and cuts frames locally (PyAV, a dependency since 1.7.1, or ffmpeg on PATH). Every frame is one image for the model. Workflow: 6 frames first; to look closer, narrow with start/end or use interval (down to 1 s). Above 12 frames the tool returns a JSON plan with frames_planned and estimated_tokens instead of images: show it to the user and call again with confirm=true only if they agree. Hard cap 120 per call. For base64 JSON with timestamps use get_video_frames_json. Read-only. Args: asset_id: The video asset's UUID. count: Frames evenly spaced over the segment (default 6). Ignored when interval > 0. size: 'thumbnail' (250px, ~1.6k tokens per frame) or 'preview' (1440px, ~6.4k). Default 'thumbnail'. start: Segment start in seconds (default 0). end: Segment end in seconds (0 = to the end). interval: One frame every N seconds instead of count (1 = one per second, the maximum granularity). confirm: Required (true) when more than 12 frames would be produced; ask the user first. sheet: Pack the frames into contact sheets (30 per image, timestamps burned in): a long video becomes one or two images instead of dozens, so no confirmation is needed. Use it to skim, then cut the moments that matter. Returns: JPEG image blocks in time order, or JSON (confirmation plan / error).

Frames of a video as base64 JPEG with timestamps, for HTML galleries and skills. Same parameters, gate (confirm above 12) and cap (120) as get_video_frames. Read-only. Args: asset_id: The video asset's UUID. count: Frames evenly spaced over the segment (default 6). Ignored when interval > 0. size: 'thumbnail' (250px, ~1.6k tokens per frame) or 'preview' (1440px, ~6.4k). Default 'thumbnail'. start: Segment start in seconds (default 0). end: Segment end in seconds (0 = to the end). interval: One frame every N seconds instead of count (1 = one per second, the maximum granularity). confirm: Required (true) when more than 12 frames would be produced; ask the user first. Returns: JSON {asset_id, duration, backend, count, frames:[{timestamp, data, type}]}, a confirmation plan {confirm_required, frames_planned, estimated_tokens, ...}, or {"error": ...}.

Comments and likes on a shared album, newest context included. Use this to read what the people an album is shared with have said about it or about one of its photos. Read-only. Args: album_id: The album whose activity to read. asset_id: Only activity on this asset within the album. activity_type: 'comment' or 'like'. Omit for both. Returns: JSON with total and an activities array (id, type, comment, asset_id, user name, created_at).

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