Immich

Immich

This connector reads one Immich photo library (Immich 3.0 or newer) through its REST API with an API key: the user and storage usage, photo and video counts, albums and who they are shared with, single photos and videos with their EXIF data, the recognised people, places and a month-by-month timeline. It is read-only: every tool is a GET request. It cannot upload, edit, favourite, archive, trash or delete assets, change albums, tags or people, or download originals, thumbnails or videos.

Setup (about 3 minutes)

1. Set IMMICH_URL to the address you open Immich at, without /api and without a trailing slash, for example https://photos.example.com or http://192.168.1.10:2283 (the default port is 2283).
2. Log in to Immich as the user whose library the AI should read, open Account Settings, API Keys, New API Key and grant only user.read, asset.read, asset.statistics, album.read and person.read. No admin account is needed, and these five permissions are the way to keep the key's access small. Copy the key (it is shown once) into IMMICH_API_KEY. It is sent in the x-api-key header.
3. Check the setup with immich_get_my_user.

Where Immich runs

• Self-hosted AnythingMCP: Immich usually lives on a home server or NAS (http://192.168.x.x:2283). The outbound SSRF guard blocks private and local addresses by default, so an administrator must allow the host through the SSRF_ALLOWED_HOSTS environment variable or the allowlist in the admin settings.
• AnythingMCP Cloud: Cloud can only reach an Immich server exposed on the public internet over HTTPS (for example behind a reverse proxy). A private IP or a local hostname is refused, and the allowlist cannot be changed on Cloud.

Privacy: an API key reads one person's photos, faces and locations. An Immich key only sees the library of the user who created it (plus albums shared with that user). Assign this connector only to MCP servers whose users may see this library. Server file paths, checksums, thumbhashes, OAuth ids and license keys are removed from the answers.

How to work

1. Totals: immich_get_asset_statistics. Without filters it counts every asset that is not in the trash, archived ones included; visibility=timeline matches the main timeline, isTrashed=true counts only the trash.
2. Albums: immich_list_albums (isShared=true for shared albums, isOwned=true for your own), then immich_get_album for one album's members, asset count and date range.
3. People: immich_search_people by name to get a person id.
4. "How many per month": immich_get_timeline_buckets with personId, albumId, tagId or isFavorite; it returns one {timeBucket, count} per month, newest first, with timeBucket as the first day of the month (2026-10-01). The same trash and archive rules as the statistics apply.
5. One photo or video: immich_get_asset for the dates, camera, lens, exposure, GPS, city, country, people and tags.
6. Places: immich_search_places by name for coordinates.

Identifiers: all ids are UUIDs. Album ids come from immich_list_albums, person ids from immich_search_people, asset ids from albumThumbnailAssetId in album answers, and tag ids from the tags of immich_get_asset.

Common errors

• 401: the API key is wrong or was deleted. 401 "Elevated permission is required": the locked folder, which an API key cannot read.
• 403 "Missing required permission": the key lacks one of the five permissions above.
• 400 "Not found or no ... access": no asset or album with that id in this library (Immich answers 400, not 404).
• 400 "Validation failed": an id is not a UUID, a value is not allowed, or name is missing on people or place search.
• 404 everywhere: IMMICH_URL is wrong or already ends in /api.
• Connection refused or blocked: on self-hosted, allow the host in the SSRF allowlist; on Cloud, the server must be public over HTTPS.

Out of scope: smart and metadata search (POST requests), uploads and any change, downloading originals, thumbnails or videos, the locked folder, shared links, memories, admin endpoints and API key management.