Skip to main content
Glama

immich-mcp

MCP server for Immich photo management. Provides AI-accessible tools for browsing, searching, organizing, and managing your self-hosted photo library — including duplicate detection and safe deletion workflows.

Features

  • 40+ MCP tools covering assets, albums, search, people, tags, shared links, activities, and duplicates

  • 3 MCP prompts for guided workflows: duplicate review, album organization, and untagged photo discovery

  • Tool annotations (title, readOnlyHint, destructiveHint, idempotentHint) for safe AI-driven automation

  • Dry-run support on all destructive operations

  • Duplicate analysis with format priority scoring and protection for favorited/album-linked assets

  • Automatic retries via httpx.AsyncHTTPTransport (configurable via IMMICH_MAX_RETRIES)

Related MCP server: jgkme/kilo-image-gen-mcp

Requirements

  • Python 3.11+

  • Immich server with API access

  • uv (recommended) or pip

Installation

git clone https://github.com/whitehara/immich-mcp
cd immich-mcp
uv pip install -e .

Configuration

Set environment variables before running:

Variable

Required

Default

Description

IMMICH_BASE_URL

Yes

—

Immich server URL (e.g. https://photos.example.com)

IMMICH_API_KEY

Yes

—

API key from Immich → Account Settings → API Keys

IMMICH_EXTERNAL_URL

No

same as IMMICH_BASE_URL

Public URL used for web_url links (useful when base URL is internal)

IMMICH_TIMEOUT

No

30.0

HTTP timeout in seconds. The /api/duplicates endpoint on large libraries (70k+ assets) can exceed 30 s — set to 120.0 or higher if immich_duplicates_list times out.

IMMICH_MAX_RETRIES

No

3

Retry attempts on transient errors

Immich API Key Permissions

Immich 1.138.0+ supports granular API key permissions. Grant the following scopes when creating your key (Immich → Account Settings → API Keys → Create).

For full functionality (all tools enabled):

Scope

Required by

server.about

immich_ping

user.read

immich_user_me

asset.read

immich_assets_list/get/view, all search tools

asset.upload

immich_assets_upload

asset.update

immich_assets_update, immich_assets_bulk_update

asset.delete

immich_assets_delete, immich_duplicates_delete

asset.statistics

immich_assets_statistics

album.read

immich_albums_list/get

album.create

immich_albums_create

album.update

immich_albums_update

album.delete

immich_albums_delete

albumAsset.create

immich_albums_add_assets

albumAsset.delete

immich_albums_remove_assets

person.read

immich_people_list/get

person.update

immich_people_update

person.merge

immich_people_merge

person.statistics

immich_people_statistics

tag.read

immich_tags_list/get

tag.create

immich_tags_create

tag.update

immich_tags_update

tag.delete

immich_tags_delete

sharedLink.read

immich_shared_links_list/get

sharedLink.create

immich_shared_links_create

sharedLink.update

immich_shared_links_update

sharedLink.delete

immich_shared_links_remove

activity.read

immich_activities_list

activity.statistics

immich_activities_statistics

activity.create

immich_activities_create

activity.delete

immich_activities_delete

duplicate.read

immich_duplicates_list

duplicate.delete

immich_duplicates_dismiss

For read-only use (no create/update/delete tools), grant only: server.about, user.read, asset.read, asset.statistics, album.read, person.read, person.statistics, tag.read, sharedLink.read, activity.read, activity.statistics, duplicate.read

On Immich versions prior to 1.138.0, select All permissions.

Usage

stdio (Claude Desktop / Claude Code)

export IMMICH_BASE_URL=https://photos.example.com
export IMMICH_API_KEY=your-api-key
immich-mcp --transport stdio

Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "immich": {
      "command": "immich-mcp",
      "args": ["--transport", "stdio"],
      "env": {
        "IMMICH_BASE_URL": "https://photos.example.com",
        "IMMICH_API_KEY": "your-api-key"
      }
    }
  }
}

HTTP (Docker / remote)

docker run -e IMMICH_BASE_URL=https://photos.example.com \
           -e IMMICH_API_KEY=your-api-key \
           -p 8000:8000 \
           ghcr.io/whitehara/immich-mcp:latest

Or build locally with docker compose up.

Default transport in Docker is streamable-http on port 8000.

Tool Reference

Annotation columns: R = readOnlyHint, D = destructiveHint, I = idempotentHint

Each tool also carries a human-readable title annotation used by MCP clients for display.

Health

Tool

Description

R

D

I

immich_ping

Verify connectivity, returns server version

✓

✓

immich_capabilities

List supported server features

✓

✓

User

Tool

Description

R

D

I

immich_user_me

Get the authenticated user's profile (name, email, quota, role)

✓

✓

Assets

Tool

Description

R

D

I

immich_assets_list

List assets with filters (favorite, archived, trashed, type)

✓

✓

immich_assets_get

Get full metadata for a single asset

✓

✓

immich_assets_view

Get thumbnail, original, and web UI URLs for an asset

✓

✓

immich_assets_upload

Upload an asset from a local file path or URL

immich_assets_update

Update favorite, archived, description, rating

✓

immich_assets_bulk_update

Bulk update multiple assets (dry_run supported)

✓

immich_assets_delete

Delete assets, optionally permanently (dry_run supported)

✓

✓

immich_assets_statistics

Get counts by asset type

✓

✓

Tool

Description

R

D

I

immich_search_metadata

Filter by date, type, location, camera, person, filename

✓

immich_search_smart

Semantic/CLIP search with natural language queries

✓

immich_search_explore

Discover popular places, people, and things

✓

✓

Albums

Tool

Description

R

D

I

immich_albums_list

List all albums

✓

✓

immich_albums_get

Get album details and assets

✓

✓

immich_albums_create

Create a new album

immich_albums_update

Update album name, description, or cover

✓

immich_albums_delete

Delete an album (assets are not deleted)

✓

✓

immich_albums_add_assets

Add assets to an album

✓

immich_albums_remove_assets

Remove assets from an album

✓

People

Tool

Description

R

D

I

immich_people_list

List recognized people

✓

✓

immich_people_get

Get person details

✓

✓

immich_people_update

Update name or visibility

✓

immich_people_merge

Merge two face clusters

✓

immich_people_statistics

Get asset count for a person

✓

✓

Tags

Tool

Description

R

D

I

immich_tags_list

List all tags

✓

✓

immich_tags_get

Get a tag by ID

✓

✓

immich_tags_create

Create a tag (use / for nested tags)

immich_tags_update

Update tag name or color

✓

immich_tags_delete

Delete a tag

✓

✓

Tool

Description

R

D

I

immich_shared_links_list

List all shared links

✓

✓

immich_shared_links_get

Get shared link details

✓

✓

immich_shared_links_create

Create a shareable URL

immich_shared_links_update

Update expiry, password, permissions

✓

immich_shared_links_remove

Revoke a shared link

✓

✓

Activities

Tool

Description

R

D

I

immich_activities_list

List comments and likes

✓

✓

immich_activities_create

Add a comment or like

immich_activities_delete

Delete an activity

✓

✓

immich_activities_statistics

Get comment count

✓

✓

Duplicates

Tool

Description

R

D

I

immich_duplicates_list

List duplicate groups with analysis (format score, resolution, protection status). Paginated (page/page_size, default 50 groups/page). Results are served from an in-memory cache; first call after server start returns cache_ready=false while data loads — large libraries may take 20–30 minutes on first load.

✓

✓

immich_duplicates_delete

Delete assets from duplicate groups (dry_run supported)

✓

✓

immich_duplicates_dismiss

Dismiss duplicate groups without deleting files (dry_run supported)

✓

✓

Pagination

immich_duplicates_list returns paginated results to avoid oversized responses on large libraries:

Parameter

Default

Description

page

1

Page number (1-based)

page_size

50

Groups per page (max 500)

The response includes total_groups, total_pages, page, and page_size fields. Iterate page=1..total_pages to process all groups.

Duplicate Analysis Fields

immich_duplicates_list with analyze=true (default) returns per-group analysis:

Field

Description

keep_id

Recommended asset to retain (highest quality)

safe_to_delete_ids

Assets not favorited and not in any album

protected_ids

Assets that are favorited or in albums — require explicit user approval

needs_review

true when protected assets appear among delete candidates

Quality Priority for keep_id (highest to lowest)

Live Photo > Format score > Resolution > File size

Favorites and album membership are tiebreakers only — they do not override a quality difference. A favorited JPEG will not be recommended over an unfavorited RAW; instead the JPEG is listed in protected_ids for user review.

Format Score (highest to lowest)

RAW/DNG > HEIC/HEIF > PNG/TIFF > JPEG > WebP > GIF

Prompt Reference

Invoke prompts from your MCP client to start guided workflows.

immich/review_duplicates

Step-by-step workflow for reviewing and safely resolving duplicate photos:

  1. Fetch duplicate groups with analysis

  2. Present summary: safe-to-delete count vs. protected assets needing review

  3. For each group, choose an action:

    • Delete: keep the best asset, move the rest to trash (or permanently delete)

    • Dismiss: assets are intentionally kept as separate copies — remove the duplicate grouping without deleting files

  4. Dry-run confirmation before execution

immich/organize_album

Guided album creation workflow:

  • Organize by date, event, person, or location

  • Uses both metadata search and semantic (CLIP) search

  • Checks for existing albums to avoid duplicates

  • Confirms asset count before creating

immich/find_untagged

Discover unorganized assets in the library:

  • Identifies assets with no album, no description, or no recognized people

  • Suggests descriptions from EXIF data

  • Hands off to immich/organize_album for album creation

Safety Model

All destructive tools (delete, merge, remove) carry destructiveHint=true in their MCP annotations, signalling to clients that human confirmation is required before execution. Additional safeguards:

  • dry_run=true is the default on all delete operations — no changes occur without explicit opt-in

  • Duplicate analysis places favorited and album-linked assets in protected_ids; they are never auto-deleted

  • Prompts explicitly instruct the AI to present a summary and obtain user approval before any destructive action

Development

# Install with dev dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

# Run a single test file
pytest tests/tools/test_assets.py -v

# Type check (optional)
pyright src/

Available Tools

43 tools
immich.activities.createC

Add a comment or like to an album or specific asset within an album.

Inputs: album_id (required), type (required), asset_id, comment.

immich.activities.deleteB
DestructiveIdempotent

Delete a comment or like by activity ID.

Inputs: activity_id (required).

immich.activities.listB
Read-onlyIdempotent

List comments and likes for an album, optionally filtered by asset.

Inputs: album_id (required), asset_id, type.

immich.activities.statisticsB
Read-onlyIdempotent

Get comment count for an album or specific asset within an album.

Inputs: album_id (required), asset_id.

immich.albums.add_assetsB
Idempotent

Add one or more assets to an album.

Inputs: album_id (required), asset_ids (required).

immich.albums.createC

Create a new album with an optional list of asset IDs.

Inputs: album_name (required), description, asset_ids.

immich.albums.deleteA
DestructiveIdempotent

Delete an album. This does not delete the assets inside it.

Inputs: album_id (required).

immich.albums.getB
Read-onlyIdempotent

Get full details of an album including its assets.

Inputs: album_id (required), without_assets.

immich.albums.listA
Read-onlyIdempotent

List all albums. Optionally filter by shared status.

Inputs: shared.

immich.albums.remove_assetsA
Idempotent

Remove one or more assets from an album. The assets themselves are not deleted.

Inputs: album_id (required), asset_ids (required).

immich.albums.updateB
Idempotent

Update album metadata: name, description, or cover asset.

Inputs: album_id (required), album_name, description, album_thumbnail_asset_id.

immich.assets.bulk_updateA
Idempotent

Update metadata for multiple assets at once. Supports dry_run to preview changes.

Inputs: asset_ids (required), is_favorite, is_archived, rating, +1 more.

immich.assets.deleteA
DestructiveIdempotent

Delete one or more assets. Set force=true to permanently delete (skip trash). Always use dry_run=true first to preview.

Inputs: asset_ids (required), force, dry_run.

immich.assets.getB
Read-onlyIdempotent

Get full metadata for a single asset by its ID.

Inputs: asset_id (required).

immich.assets.listB
Read-onlyIdempotent

List assets with optional filters. Returns paginated results.

Inputs: page, page_size, is_favorite, is_archived, +2 more.

immich.assets.statisticsB
Read-onlyIdempotent

Get asset counts broken down by type (images, videos, total).

Inputs: no named parameters.

immich.assets.updateB
Idempotent

Update metadata for a single asset (favorite, archived, description, rating).

Inputs: asset_id (required), is_favorite, is_archived, description, +1 more.

immich.assets.uploadA

Upload an asset to Immich from a local file path or a URL. For file paths, the MCP server process must have read access to the file. For URLs (http/https), the server downloads the file then uploads it to Immich.

Inputs: source (required), device_asset_id, file_created_at, file_modified_at, +1 more.

immich.assets.viewA
Read-onlyIdempotent

Get direct URLs for viewing or downloading an asset. Returns thumbnail, original file, and Immich web UI links. URLs include the API key as a query parameter for direct browser access.

Inputs: asset_id (required).

immich.capabilitiesB
Read-onlyIdempotent

Discover Immich server features and supported API capabilities.

Inputs: no named parameters.

immich.duplicates.deleteA
DestructiveIdempotent

Delete specific assets from duplicate groups. Always run with dry_run=true first to confirm what will be deleted. Set force=true to permanently delete (bypass trash). Do NOT delete assets that are favorited or belong to albums without explicit user approval.

Inputs: asset_ids (required), force, dry_run.

immich.duplicates.dismissA
DestructiveIdempotent

Dismiss duplicate groups without deleting any assets. Use this when the assets are intentionally kept as separate copies and should no longer appear in the duplicate list. The asset files are NOT deleted — only the duplicate grouping is removed. Always run with dry_run=true first.

Inputs: duplicate_ids (required), dry_run.

immich.duplicates.listA
Read-onlyIdempotent

List all duplicate asset groups detected by Immich. Each group contains assets with matching content hashes. Returns full metadata needed for deletion decisions: file format, size, resolution, favorite status, album membership, Live Photo status.

Inputs: analyze.

immich.people.getB
Read-onlyIdempotent

Get details for a specific person by ID.

Inputs: person_id (required).

immich.people.listA
Read-onlyIdempotent

List all recognized people from face recognition. Supports pagination.

Inputs: page, page_size, with_hidden.

immich.people.mergeA
Destructive

Merge two person clusters into one. The source person will be merged into the target.

Inputs: target_person_id (required), source_person_id (required).

immich.people.statisticsB
Read-onlyIdempotent

Get asset count statistics for a specific person.

Inputs: person_id (required).

immich.people.updateB
Idempotent

Update a person's name or visibility (hidden/visible).

Inputs: person_id (required), name, is_hidden.

immich.pingA
Read-onlyIdempotent

Verify connectivity and authentication with the Immich server. Returns server version and status.

Inputs: no named parameters.

immich.search.exploreB
Read-onlyIdempotent

Get discovery data: popular places, recognized people, and notable things in your library.

Inputs: no named parameters.

immich.search.metadataB
Read-only

Search assets using metadata filters: date range, type, location, camera model, person, filename.

Inputs: query, type, is_favorite, is_archived, +9 more.

immich.search.smartA
Read-only

Semantic search using CLIP/ML. Describe what you're looking for in natural language (e.g. 'sunset at the beach', 'birthday party').

Inputs: query (required), type, is_favorite, page, +1 more.

immich.shared_links.createC

Create a shareable link for an album or specific assets. Optionally set expiry and password.

Inputs: type (required), album_id, asset_ids, expires_at, +5 more.

immich.shared_links.getB
Read-onlyIdempotent

Get details of a specific shared link by ID.

Inputs: shared_link_id (required).

immich.shared_links.listB
Read-onlyIdempotent

List all shared links.

Inputs: no named parameters.

immich.shared_links.removeA
DestructiveIdempotent

Remove a shared link, revoking access to its content.

Inputs: shared_link_id (required).

immich.shared_links.updateB
Idempotent

Update shared link settings: expiry, password, download permission.

Inputs: shared_link_id (required), expires_at, allow_download, allow_upload, +3 more.

immich.tags.createA

Create a new tag. Use '/' as separator for nested tags (e.g. 'Travel/Japan').

Inputs: name (required), color.

immich.tags.deleteB
DestructiveIdempotent

Delete a tag by ID.

Inputs: tag_id (required).

immich.tags.getB
Read-onlyIdempotent

Get details of a specific tag by ID.

Inputs: tag_id (required).

immich.tags.listB
Read-onlyIdempotent

List all tags in the library.

Inputs: no named parameters.

immich.tags.updateB
Idempotent

Update a tag's name or color.

Inputs: tag_id (required), name, color.

immich.user.meA
Read-onlyIdempotent

Get the profile of the currently authenticated user (name, email, quota, role).

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 43 tools

    Disambiguation4/5

    Tools are well-organized by resource categories (e.g., assets, albums, people, duplicates), with clear distinctions within each group. However, some potential overlap exists between 'immich.assets.list' and 'immich.search.metadata' for filtering assets, though their primary purposes differ (general listing vs. targeted search).

    Naming Consistency5/5

    Naming follows a highly consistent pattern: all tools use snake_case with a clear 'immich.resource.action' structure (e.g., 'immich.albums.create', 'immich.people.update'). This uniformity makes the toolset predictable and easy to navigate across all 43 tools.

    Tool Count3/5

    With 43 tools, the count is high and may feel heavy for an MCP server, potentially overwhelming for agents. While the domain (photo management) is broad, the toolset could benefit from consolidation or scoping down to core workflows to improve usability.

    Completeness5/5

    The toolset provides comprehensive coverage for photo management, including full CRUD operations for assets, albums, people, tags, and shared links, plus advanced features like duplicates handling, search, and statistics. No obvious gaps are present; agents can perform end-to-end workflows without dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      This MCP server enables AI tools to interact with your Apple Photos library via the osxphotos CLI, providing tools for querying and managing photos.
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An OpenAPI 3.0-based MCP server that provides structured access to Immich 2.0 server functionality through tools, resources, and contextual capabilities.
      3
      MIT