Skip to main content
Glama
drolosoft

immich-photo-manager

by drolosoft
OverviewSchemaRelated ServersScoreDiscussions
Remote

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
PYTHONPATHNoAbsolute path to the src/ directory of the cloned repository (required for manual setup)
MCP_TRANSPORTNoThe MCP transport mode (default is stdio)stdio
IMMICH_API_KEYYesYour Immich API key (required for authentication)
IMMICH_BASE_URLYesThe base URL of your Immich instance (e.g., https://your-immich-server.com)

Capabilities

Features and capabilities supported by this server

CapabilityDetails
tools
{
  "listChanged": false
}
prompts
{
  "listChanged": false
}
resources
{
  "subscribe": false,
  "listChanged": false
}
experimental
{}

Tools

Functions exposed to the LLM to take actions

NameDescription
pingA

Check 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).
get_server_versionA

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_statisticsA

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

Update 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.
get_asset_infoA

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

Returns: JSON with EXIF data, GPS, dates, dimensions, file size, camera make/model, and owner.
update_asset_metadataA

Update 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.
rotate_assetsA

Apply 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.
revert_asset_editsA

Remove 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.
get_map_markersA

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

Search 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_smartA

AI-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.
list_albumsA

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

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 and a flat list of all asset_ids in the album.
create_albumA

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

Update 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.
delete_albumA

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 deleted confirmation and album_id.
add_assets_to_albumA

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

Remove 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.
get_asset_thumbnailA

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

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_thumbnails_batchA

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

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

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

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

Update 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.
delete_shared_linkA

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

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

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

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

Update 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.
merge_peopleA

Merge 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.
search_peopleA

Search 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.
get_person_thumbnailA

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_asset_facesA

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

Reassign 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.
delete_assetsA

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

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

Restore 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.
restore_assetsA

Restore 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.
get_duplicatesA

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

Resolve 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.
list_tagsA

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

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

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

Update 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.
delete_tagA

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 deleted confirmation and tag_id.
tag_assetsA

Apply 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_assetsA

Remove 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.
upload_assetA

Upload 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.
list_assetsA

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

Prompts

Interactive templates invoked by user choice

NameDescription

No prompts

Resources

Contextual data attached and managed by the client

NameDescription

No resources

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