immich-mcp
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 automationDry-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 viaIMMICH_MAX_RETRIES)
Related MCP server: jgkme/kilo-image-gen-mcp
Requirements
Python 3.11+
Immich server with API access
uv(recommended) orpip
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 |
| Yes | — | Immich server URL (e.g. |
| Yes | — | API key from Immich → Account Settings → API Keys |
| No | same as | Public URL used for |
| No |
| HTTP timeout in seconds. The |
| No |
| 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 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 stdioClaude 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:latestOr 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 |
| Verify connectivity, returns server version | ✓ | ✓ | |
| List supported server features | ✓ | ✓ |
User
Tool | Description | R | D | I |
| Get the authenticated user's profile (name, email, quota, role) | ✓ | ✓ |
Assets
Tool | Description | R | D | I |
| List assets with filters (favorite, archived, trashed, type) | ✓ | ✓ | |
| Get full metadata for a single asset | ✓ | ✓ | |
| Get thumbnail, original, and web UI URLs for an asset | ✓ | ✓ | |
| Upload an asset from a local file path or URL | |||
| Update favorite, archived, description, rating | ✓ | ||
| Bulk update multiple assets (dry_run supported) | ✓ | ||
| Delete assets, optionally permanently (dry_run supported) | ✓ | ✓ | |
| Get counts by asset type | ✓ | ✓ |
Search
Tool | Description | R | D | I |
| Filter by date, type, location, camera, person, filename | ✓ | ||
| Semantic/CLIP search with natural language queries | ✓ | ||
| Discover popular places, people, and things | ✓ | ✓ |
Albums
Tool | Description | R | D | I |
| List all albums | ✓ | ✓ | |
| Get album details and assets | ✓ | ✓ | |
| Create a new album | |||
| Update album name, description, or cover | ✓ | ||
| Delete an album (assets are not deleted) | ✓ | ✓ | |
| Add assets to an album | ✓ | ||
| Remove assets from an album | ✓ |
People
Tool | Description | R | D | I |
| List recognized people | ✓ | ✓ | |
| Get person details | ✓ | ✓ | |
| Update name or visibility | ✓ | ||
| Merge two face clusters | ✓ | ||
| Get asset count for a person | ✓ | ✓ |
Tags
Tool | Description | R | D | I |
| List all tags | ✓ | ✓ | |
| Get a tag by ID | ✓ | ✓ | |
| Create a tag (use | |||
| Update tag name or color | ✓ | ||
| Delete a tag | ✓ | ✓ |
Shared Links
Tool | Description | R | D | I |
| List all shared links | ✓ | ✓ | |
| Get shared link details | ✓ | ✓ | |
| Create a shareable URL | |||
| Update expiry, password, permissions | ✓ | ||
| Revoke a shared link | ✓ | ✓ |
Activities
Tool | Description | R | D | I |
| List comments and likes | ✓ | ✓ | |
| Add a comment or like | |||
| Delete an activity | ✓ | ✓ | |
| Get comment count | ✓ | ✓ |
Duplicates
Tool | Description | R | D | I |
| List duplicate groups with analysis (format score, resolution, protection status). Paginated ( | ✓ | ✓ | |
| Delete assets from duplicate groups (dry_run supported) | ✓ | ✓ | |
| 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 number (1-based) |
|
| 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 |
| Recommended asset to retain (highest quality) |
| Assets not favorited and not in any album |
| Assets that are favorited or in albums — require explicit user approval |
|
|
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_albumfor 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=trueis the default on all delete operations — no changes occur without explicit opt-inDuplicate analysis places favorited and album-linked assets in
protected_ids; they are never auto-deletedPrompts 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 toolsimmich.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.deleteBDestructiveIdempotent
Delete a comment or like by activity ID.
Inputs: activity_id (required).
immich.activities.listBRead-onlyIdempotent
List comments and likes for an album, optionally filtered by asset.
Inputs: album_id (required), asset_id, type.
immich.activities.statisticsBRead-onlyIdempotent
Get comment count for an album or specific asset within an album.
Inputs: album_id (required), asset_id.
immich.albums.add_assetsBIdempotent
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.deleteADestructiveIdempotent
Delete an album. This does not delete the assets inside it.
Inputs: album_id (required).
immich.albums.getBRead-onlyIdempotent
Get full details of an album including its assets.
Inputs: album_id (required), without_assets.
immich.albums.listARead-onlyIdempotent
List all albums. Optionally filter by shared status.
Inputs: shared.
immich.albums.remove_assetsAIdempotent
Remove one or more assets from an album. The assets themselves are not deleted.
Inputs: album_id (required), asset_ids (required).
immich.albums.updateBIdempotent
Update album metadata: name, description, or cover asset.
Inputs: album_id (required), album_name, description, album_thumbnail_asset_id.
immich.assets.bulk_updateAIdempotent
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.deleteADestructiveIdempotent
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.getBRead-onlyIdempotent
Get full metadata for a single asset by its ID.
Inputs: asset_id (required).
immich.assets.listBRead-onlyIdempotent
List assets with optional filters. Returns paginated results.
Inputs: page, page_size, is_favorite, is_archived, +2 more.
immich.assets.statisticsBRead-onlyIdempotent
Get asset counts broken down by type (images, videos, total).
Inputs: no named parameters.
immich.assets.updateBIdempotent
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.viewARead-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.capabilitiesBRead-onlyIdempotent
Discover Immich server features and supported API capabilities.
Inputs: no named parameters.
immich.duplicates.deleteADestructiveIdempotent
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.dismissADestructiveIdempotent
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.listARead-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.getBRead-onlyIdempotent
Get details for a specific person by ID.
Inputs: person_id (required).
immich.people.listARead-onlyIdempotent
List all recognized people from face recognition. Supports pagination.
Inputs: page, page_size, with_hidden.
immich.people.mergeADestructive
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.statisticsBRead-onlyIdempotent
Get asset count statistics for a specific person.
Inputs: person_id (required).
immich.people.updateBIdempotent
Update a person's name or visibility (hidden/visible).
Inputs: person_id (required), name, is_hidden.
immich.pingARead-onlyIdempotent
Verify connectivity and authentication with the Immich server. Returns server version and status.
Inputs: no named parameters.
immich.search.exploreBRead-onlyIdempotent
Get discovery data: popular places, recognized people, and notable things in your library.
Inputs: no named parameters.
immich.search.metadataBRead-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.smartARead-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.tags.createA
Create a new tag. Use '/' as separator for nested tags (e.g. 'Travel/Japan').
Inputs: name (required), color.
immich.tags.deleteBDestructiveIdempotent
Delete a tag by ID.
Inputs: tag_id (required).
immich.tags.getBRead-onlyIdempotent
Get details of a specific tag by ID.
Inputs: tag_id (required).
immich.tags.listBRead-onlyIdempotent
List all tags in the library.
Inputs: no named parameters.
immich.tags.updateBIdempotent
Update a tag's name or color.
Inputs: tag_id (required), name, color.
immich.user.meARead-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
Scored across 43 tools
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 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.
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.
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
Related MCP Connectors
Hosted MCP server for AI photo editing: nothing to install, no desktop photo editor needed.
MCP server exposing the YourImageShare upload API (upload/list/delete) as tools for AI agents.
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceThis MCP server aids users in searching and analyzing their photo library by location, labels, and people, offering functionalities like photo analysis and fuzzy matching for enhanced photo management.25MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for generating, editing, and processing images via multiple providers including Kilo, OpenRouter, OpenAI, and Gemini, with local tools for background removal, resizing, and cropping.16 npm3MIT
- AlicenseNot gradedqualityDmaintenanceThis MCP server enables AI tools to interact with your Apple Photos library via the osxphotos CLI, providing tools for querying and managing photos.2MIT
- AlicenseNot gradedqualityDmaintenanceAn OpenAPI 3.0-based MCP server that provides structured access to Immich 2.0 server functionality through tools, resources, and contextual capabilities.3MIT