immich-mcp
Provides read-only access to an Immich photo library, allowing AI agents to search photos by visual context, OCR text, and metadata such as people, places, dates, albums, filenames, and descriptions; retrieve photo details and OCR text; view images; and list people and albums.
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 an AI agent find and look at photos in your Immich library — the same three searches as the Immich app, shaped as workflows rather than raw endpoints:
Tool | Search by | Example |
| context — what the photo shows (CLIP smart search) | "sunrise on the beach" |
| text in the image (OCR) | "check out receipt", "wifi password" |
| file name, description, people, place, date, album | "videos of Ada in Mexico, 2024" |
| one photo's details and full OCR text | |
| the image itself, returned as MCP image content | |
| the names the filters accept |
It is read-only: no tool uploads, edits, moves or deletes anything, and every tool is annotated
readOnlyHint.
Why it is more than an API wrapper
Filters take plain names.
people: ["jose"]finds "José Núñez";city: "zurich"is resolved to the "Zürich" Immich stored (its place filter is exact and case-sensitive); an album can be given by name. Ambiguous or unknown names fail with the candidates, so the model can correct itself. Each result reports what the names resolved to underapplied.Dates are calendar periods in your zone.
takenFrom: "2024-06", takenTo: "2024-06"is all of June 2024 as lived inTZ, DST included. Timestamps keep their offset.OCR results say why they matched: each hit carries the matching lines of text.
Compact results: about ten fields per photo instead of Immich's ~40, plus a link to open it in Immich. Live Photo video halves, hidden and locked items are excluded; archived on request.
The model can see the photo (
view_photo), to check a match before describing it.
Related MCP server: Apple Photos MCP
Requirements
Immich v3.2 or newer (it uses the
filtersearch API introduced in 3.2; tested on 3.4.2), with Smart Search and OCR enabled for the context and text searches.An API key (Account Settings → API Keys) with at least
asset.read,asset.view,person.readandalbum.read.
Run it
Docker (Streamable HTTP)
docker run -d --name immich-mcp -p 127.0.0.1:3000:3000 \
-e IMMICH_URL=https://photos.example.com \
-e IMMICH_API_KEY=... \
-e TZ=America/Chicago \
ghcr.io/miguelarios/immich-mcp:0.1.0
curl -s http://127.0.0.1:3000/healthz # okThe endpoint is http://127.0.0.1:3000/mcp. Compose:
services:
immich-mcp:
image: ghcr.io/miguelarios/immich-mcp:0.1.0
restart: unless-stopped
environment:
IMMICH_URL: https://photos.example.com
IMMICH_API_KEY: ${IMMICH_API_KEY:?set in .env}
TZ: America/Chicago
ports:
- "127.0.0.1:3000:3000"From source (stdio or HTTP)
npm ci && npm run build
IMMICH_URL=... IMMICH_API_KEY=... node dist/bin/cli.js # stdio
IMMICH_MCP_TRANSPORT=http IMMICH_URL=... IMMICH_API_KEY=... node dist/bin/cli.js # HTTP :3000Connect a client
claude mcp add --transport http immich http://127.0.0.1:3000/mcp
hermes mcp add immich --url http://127.0.0.1:3000/mcpOther clients: {"type": "http", "url": "http://127.0.0.1:3000/mcp"}.
Configuration
Variable | Default | |
| required | Server origin; a trailing |
| required | See the permissions above |
|
| Origin for links returned to the user, when the API is reached privately ( |
|
| Zone bare dates are read in |
|
| Per-request timeout |
|
| |
|
| |
|
| |
| none | Browser origins admitted; requests without |
Security
The MCP endpoint does no authentication. Anyone who can reach the port can search and view
your whole library with your API key. Bind it to loopback (as above) or a private network, and
put an OAuth proxy in front before exposing it anywhere else. Browser requests from origins not in
IMMICH_MCP_HTTP_ALLOWED_ORIGINS are refused, which blocks DNS-rebinding attacks from web pages.
Protocol
Streamable HTTP at /mcp (health at /healthz), or stdio. Clients on protocol revision
2026-07-28 are served statelessly, one request at a time; 2025-era clients get a session
(Mcp-Session-Id, closed after 30 minutes idle).
Development
npm ci
npm test && npm run lint && npm run typecheck && npm run buildSee CLAUDE.md for the architecture and conventions, and docs/design.md for the decisions behind the tool set.
License
MIT
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
Search and license documentary photos. AI agents pay on their own with a prepaid wallet key.
Search photos/videos; manage collections, people and duplicates. Requires paid OwAI Cloud Access.
Search over 1.85 million captioned images using text, a reference image, or both. Upload a JPEG, PNG, or WebP image as base64, or provide a public HTTPS image URL. Find similar images from a Lightdrift asset ID and retrieve hosted file URLs, source licenses, and attribution. Connect with OAuth or an API key. Searches cost $0.005 ($5 per 1,000); image details are free. Setup: https://docs.lightdrift.ai/guides/images-mcp
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- AlicenseAqualityBmaintenanceEnables AI agents to search, inspect, organize, and export photos from a local Apple Photos library using natural language, including scene labels, text, faces, places, and albums.131MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to search, list, preview, and export photos from Apple Photos, Google Photos Picker sessions, and local Google Takeout archives using native search and metadata inspection.MIT
- AlicenseNot gradedqualityCmaintenanceEnables ChatGPT users to search and browse a private photo library, inspect metadata, and receive real image previews through read-only tools, while keeping encrypted sessions server-side.MIT