Which integrations are available for this server?

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

How do I use immich-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@immich-mcp find photos of sunsets from last summer" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

de en es ja ko ru zh

immich-mcp

by whitehara

Overview Schema Related Servers Score Discussions

Python

Remote

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)

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	✓		✓

Search

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	✓		✓

Shared Links

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:

Fetch duplicate groups with analysis
Present summary: safe-to-delete count vs. protected assets needing review
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
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/

Install Server

license - not found

quality

maintenance

How are these scores calculated?

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Latest Blog Posts

Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
open source
OpenAI
Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security

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/whitehara/immich-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

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		✓	✓

immich-mcp

Features

Requirements

Installation

Configuration

Immich API Key Permissions

Usage

stdio (Claude Desktop / Claude Code)

HTTP (Docker / remote)

Tool Reference

Health

User

Assets

Search

Albums

People

Tags

Shared Links

Activities

Duplicates

Pagination

Duplicate Analysis Fields

Quality Priority for keep_id (highest to lowest)

Format Score (highest to lowest)

Prompt Reference

immich/review_duplicates

immich/organize_album

immich/find_untagged

Safety Model

Development

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API

Quality Priority for `keep_id` (highest to lowest)

`immich/review_duplicates`

`immich/organize_album`

`immich/find_untagged`