immich-mcp
Allows searching, viewing, and tidying up an Immich photo library, including smart photo search, image viewing, photo details, metadata and tag edits, people/face management, and limited admin operations, without deleting or uploading anything.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
immich-mcp
An MCP server that lets Claude (or any MCP client) search, look at and tidy up an Immich photo library — signed in with your normal Immich email and password, acting only as you, and unable to delete anything.
Run it next to Immich, put it behind the same domain (https://photos.example.com/mcp), and add that URL
as a custom connector in claude.ai or the Claude mobile app. Everyone in the household with an Immich
account can connect with their own login and sees only their own library.
Why another Immich MCP?
The existing Immich MCP servers are good at exposing Immich's API. They were built for one person running them on their own machine, with one API key pasted into a config file. That breaks down when you want to use your photos from claude.ai or your phone, or share the server with family:
immich-mcp | Typical Immich MCP | |
Works as a claude.ai / mobile connector | Yes: built-in OAuth 2.1 (discovery, dynamic client registration, PKCE, refresh rotation) | Local stdio, or HTTP with no auth, or OAuth only via a separate identity provider you run |
How you sign in | Your Immich email and password, on a page served by this server | Paste an API key into a config file |
Who it acts as | Each user as themselves; any number of users | Whoever owns the one configured key |
Credentials on the server | A per-user API key it creates for itself, encrypted at rest; your password is never stored | A long-lived API key in a config file or environment variable |
Revoking access | Delete the key "Claude (immich-mcp)" in Immich → Account Settings → API Keys | Edit config files and restart |
Deleting photos | Impossible: the key is created without any | Usually available, sometimes behind a confirm flag |
Tool design | 15 task-shaped tools, plus 4 for admins (one search tool with every filter, names accepted wherever ids are) | Dozens to hundreds of tools mirroring API endpoints |
Seeing photos |
| Varies; often links or IDs only |
Extra services to run | None (one container, SQLite) | Sometimes an identity provider (e.g. Pocket-ID) |
Choose something else if you want the whole Immich API (uploads, album management, sharing, trash, duplicates, galleries or PDF export) on your own desktop: immich-photo-manager and ImmichMCP cover far more of it. mcp4immich maps every endpoint and can sit behind your own OIDC provider. This project deliberately does less, so it is safe to leave on the internet for the whole family.
Related MCP server: semantic-image-search-mcp
What it can do
Find and see
search_photos— natural-language smart search ("kids on a beach at sunset") combined with filters for people, city/state/country, date range, photo/video, favorite, rating, album, tags, text in the photo (OCR), file name, description and cameraview_photos— returns up to 4 large (~1440 px) or 16 small (~250 px) images for the model to look atget_photo_details— date and time zone, place and GPS, camera and exposure, description, rating, tags, every detected face with its box and person, optionally OCR textlist_people,list_albums,list_tags,search_suggestions(exact place and camera names),about_connection
Edit details
update_photos— description, favorite, rating, date taken, location (for one or many photos)tag_photos,untag_photos— tags are created as needed, nested asParent/Child
People and faces
update_person— name, birth date, hidden, favoritecreate_person,reassign_face— fix faces Immich assigned to the wrong personmerge_people— combine people Immich split up
Admins only (offered only when the signed-in user is an Immich admin)
admin_server_overview,admin_list_users,admin_job_queuesadmin_queue_control— start (unprocessed items only, never a forced re-run), pause, resume
Not available, by design: deleting or trashing anything, album changes, sharing and shared links, uploads, server settings, user management.
How sign-in works
The MCP client discovers the server through
/.well-known/oauth-protected-resource/mcpand registers itself.You see a sign-in page on your own domain that names the app asking and says what it may do.
Your email and password go to Immich once. The server creates an API key named "Claude (immich-mcp)" in your account with only the permissions the tools need, then logs that password session out.
The client gets an access token (1 hour) and a rotating refresh token (90 days). A refresh token used twice ends the sign-in. Only hashes of tokens are stored; the Immich key is encrypted with AES-256-GCM.
Signing in again from the same app replaces the old key. If Immich rejects the key (you deleted it), the connection ends and the app asks you to sign in again.
Redirect URIs are limited to Claude's callbacks and loopback addresses by default (ALLOWED_REDIRECT_URIS).
Running it
Requires Immich v3 (tested with v3.4.2) with password login enabled.
# next to Immich's docker-compose.yml
services:
immich-mcp:
image: ghcr.io/tonimelisma/immich-mcp:latest
environment:
PUBLIC_URL: https://photos.example.com/mcp
IMMICH_URL: http://immich_server:2283
volumes:
- ./immich-mcp:/data
ports:
- '127.0.0.1:8080:8080'
restart: alwaysRoute the MCP paths to it in your reverse proxy, everything else stays with Immich. For nginx:
location /mcp {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
location ~ ^/\.well-known/(oauth-protected-resource|oauth-authorization-server|openid-configuration)/mcp {
proxy_pass http://127.0.0.1:8080;
}Then in claude.ai: Settings → Connectors → Add custom connector → https://photos.example.com/mcp.
Variable | Default | Meaning |
| (required) | Public URL of the MCP endpoint; also the OAuth issuer |
| (required) | How this server reaches Immich |
| origin of | Base for photo links in results |
|
| SQLite database and generated encryption key |
| generated into | Base64 32-byte key; set it to keep the key out of the data directory |
| Claude callbacks, loopback | Comma-separated; exact URIs or |
|
| Seconds |
|
| Express |
|
| Name of the key created in Immich |
|
| Listen address |
Development
npm install
npm run check # typecheck, lint, unit tests
docker compose -f e2e/docker-compose.yml up -d --wait # throwaway Immich on 127.0.0.1:2299
npm run test:e2e # sign-in and every tool against itThe end-to-end suite never touches a real library: it creates its own admin, user, photos, people and faces in a container whose data lives in memory.
License
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Search photos and video moments by visual meaning, people, dates, and folders across local libraries, Apple Photos, and OneDrive. Manage collections, groups, favorites, people, and duplicate review. Synced metadata remains searchable while the desktop is offline; local and Apple Photos media access needs the owning device online with remote access enabled. OneDrive media can be accessed directly from the cloud. OAuth or Bearer API keys. Paid Cloud Access required; hosted visual search uses prepaid credits. Text-in-image search is semantic matching, not guaranteed exact OCR. Setup: https://organizewith.ai/en/guides/connect-ai-assistants
Holiday photo MCP server: list and fetch personal holiday photos inline in Claude chat.
Search photos/videos; manage collections, people and duplicates. Requires paid OwAI Cloud Access.
Connect Claude to your Platform7n workspaces: chat, links, work and decks. One-click OAuth.
Related MCP Servers
AlicenseNot gradedqualityDmaintenanceExposes a visual library with semantic search, tagging, editing, and management of photos as tools for AI agents like Claude Code.13 npm49MIT- AlicenseAqualityCmaintenanceEnables natural language search of local photo archives using AI-powered semantic understanding, with integration into Claude Desktop via the Model Context Protocol.42MIT
- FlicenseNot gradedqualityCmaintenanceEnables users to search and retrieve photos from a self-hosted Immich photo library via natural language, supporting CLIP-based semantic search, metadata filtering, album browsing, and share link creation.-
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to search a self-hosted photo and video library, view photos, and manage albums through MCP, with all actions scoped to the connected account and vault items hidden.1AGPL 3.0