Skip to content
Back to search

immich-mcp

MCP server for Immich photo retrieval: search by context (CLIP), by text in the image (OCR) and by metadata, then view the photo

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/miguelarios--immich-mcp/badge.svg)](/listings/miguelarios--immich-mcp)

HTML

<a href="/listings/miguelarios--immich-mcp"><img src="/api/listings/miguelarios--immich-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 185 lines
  1. # immich-mcp
  2. An [MCP](https://modelcontextprotocol.io) server that lets an AI agent find and look at photos in
  3. your [Immich](https://immich.app) library — the same three searches as the Immich app, shaped as
  4. workflows rather than raw endpoints:
  5. | Tool | Search by | Example |
  6. | --- | --- | --- |
  7. | `search_photos` | **context** — what the photo shows (CLIP smart search) | "sunrise on the beach" |
  8. | `search_photo_text` | **text in the image** (OCR) | "check out receipt", "wifi password" |
  9. | `search_photo_metadata` | file name, description, people, place, date, album | "videos of Ada in Mexico, 2024" |
  10. | `get_photo` | one photo's details and full OCR text | |
  11. | `view_photo` | the image itself, returned as MCP image content | |
  12. | `list_people` / `list_albums` | the names the filters accept | |
  13. It is **read-only**: no tool uploads, edits, moves or deletes anything, and every tool is annotated
  14. `readOnlyHint`.
  15. ## Why it is more than an API wrapper
  16. - **Filters take plain names.** `people: ["jose"]` finds "José Núñez"; `city: "zurich"` is
  17. resolved to the "Zürich" Immich stored (its place filter is exact and case-sensitive); an album
  18. can be given by name. Ambiguous or unknown names fail with the candidates, so the model can
  19. correct itself. Each result reports what the names resolved to under `applied`.
  20. - **Dates are calendar periods in your zone.** `takenFrom: "2024-06", takenTo: "2024-06"` is all of
  21. June 2024 as lived in `TZ`, DST included. Timestamps keep their offset.
  22. - **OCR results say why they matched**: each hit carries the matching lines of text.
  23. - **Compact results**: about ten fields per photo instead of Immich's ~40, plus a link to open it
  24. in Immich. Live Photo video halves, hidden and locked items are excluded; archived on request.
  25. - **The model can see the photo** (`view_photo`), to check a match before describing it.
  26. ## Requirements
  27. - Immich **v3.2 or newer** (it uses the `filter` search API introduced in 3.2; tested on 3.4.2),
  28. with Smart Search and OCR enabled for the context and text searches.
  29. - An API key (Account Settings → API Keys) with at least `asset.read`, `asset.view`,
  30. `person.read` and `album.read`.
  31. ## Run it
  32. ### Docker (Streamable HTTP)
  33. ```bash
  34. docker run -d --name immich-mcp -p 127.0.0.1:3000:3000 \
  35. -e IMMICH_URL=https://photos.example.com \
  36. -e IMMICH_API_KEY=... \
  37. -e TZ=America/Chicago \
  38. ghcr.io/miguelarios/immich-mcp:0.1.0
  39. curl -s http://127.0.0.1:3000/healthz # ok
  40. ```
  41. The endpoint is `http://127.0.0.1:3000/mcp`. Compose:
  42. ```yaml
  43. services:
  44. immich-mcp:
  45. image: ghcr.io/miguelarios/immich-mcp:0.1.0
  46. restart: unless-stopped
  47. environment:
  48. IMMICH_URL: https://photos.example.com
  49. IMMICH_API_KEY: ${IMMICH_API_KEY:?set in .env}
  50. TZ: America/Chicago
  51. ports:
  52. - "127.0.0.1:3000:3000"
  53. ```
  54. ### For a household (sign-in)
  55. With `IMMICH_MCP_AUTH=oauth` the server can face the internet: each person adds the URL to Claude
  56. (or any MCP client that does OAuth), signs in with their Immich email and password on the sign-in
  57. page, and from then on searches only what their Immich account can see. (They can paste an API
  58. key of their own instead.)
  59. ```yaml
  60. services:
  61. immich-mcp:
  62. image: ghcr.io/miguelarios/immich-mcp:0.2.0
  63. restart: unless-stopped
  64. environment:
  65. IMMICH_URL: http://immich-server:2283 # reached privately
  66. IMMICH_PUBLIC_URL: https://photos.example.com # for links and the sign-in page
  67. IMMICH_MCP_AUTH: oauth
  68. IMMICH_MCP_PUBLIC_URL: https://photos-mcp.example.com
  69. IMMICH_MCP_SECRET: ${IMMICH_MCP_SECRET:?openssl rand -base64 48}
  70. TZ: America/Chicago
  71. ```
  72. Put it behind your TLS reverse proxy on **its own hostname** (OAuth discovery lives at the root of
  73. the origin), and add `https://photos-mcp.example.com/mcp` as a connector. There is no volume: the
  74. server stores nothing. See [Security](#security) for what that means.
  75. ### From source (stdio or HTTP)
  76. ```bash
  77. npm ci && npm run build
  78. IMMICH_URL=... IMMICH_API_KEY=... node dist/bin/cli.js # stdio
  79. IMMICH_MCP_TRANSPORT=http IMMICH_URL=... IMMICH_API_KEY=... node dist/bin/cli.js # HTTP :3000
  80. ```
  81. ### Connect a client
  82. ```bash
  83. claude mcp add --transport http immich http://127.0.0.1:3000/mcp
  84. hermes mcp add immich --url http://127.0.0.1:3000/mcp
  85. ```
  86. Other clients: `{"type": "http", "url": "http://127.0.0.1:3000/mcp"}`.
  87. ## Configuration
  88. | Variable | Default | |
  89. | --- | --- | --- |
  90. | `IMMICH_URL` | required | Server origin; a trailing `/api` is accepted |
  91. | `IMMICH_API_KEY` | required, unless sign-in is on | See the permissions above |
  92. | `IMMICH_PUBLIC_URL` | `IMMICH_URL` | Origin for links returned to the user, when the API is reached privately (`http://immich-server:2283`) |
  93. | `TZ` | `UTC` | Zone bare dates are read in |
  94. | `IMMICH_TIMEOUT_MS` | `30000` | Per-request timeout |
  95. | `IMMICH_MCP_TRANSPORT` | `stdio` (`http` in the image) | |
  96. | `IMMICH_MCP_HTTP_HOST` | `127.0.0.1` (`0.0.0.0` in the image) | |
  97. | `IMMICH_MCP_HTTP_PORT` | `3000` | |
  98. | `IMMICH_MCP_HTTP_ALLOWED_ORIGINS` | none | Browser origins admitted; requests without `Origin` are always allowed |
  99. | `IMMICH_MCP_AUTH` | `none` | `oauth` turns on sign-in (HTTP only); `IMMICH_API_KEY` must then be unset |
  100. | `IMMICH_MCP_PUBLIC_URL` | required with `oauth` | The origin clients use, no path; https unless loopback |
  101. | `IMMICH_MCP_SECRET` | required with `oauth` | 32+ characters; seals client ids and tokens. Changing it signs everyone out |
  102. | `IMMICH_MCP_OAUTH_REDIRECT_URIS` | none | Extra redirect URIs to admit, comma-separated |
  103. | `IMMICH_MCP_PASSWORD_SIGN_IN` | `true` | `false` removes the email-and-password form, leaving paste-a-key |
  104. ## Security
  105. **Without sign-in (the default) the MCP endpoint does no authentication.** Anyone who can reach
  106. the port can search and view your whole library with your API key. Bind it to loopback or a private
  107. network. Browser requests from origins not in `IMMICH_MCP_HTTP_ALLOWED_ORIGINS` are refused, which
  108. blocks DNS-rebinding attacks from web pages.
  109. **With `IMMICH_MCP_AUTH=oauth`** the server is an OAuth 2.1 authorization server for itself
  110. (discovery, dynamic client registration, PKCE S256, tokens bound to this server), and `/mcp`
  111. answers only a valid token:
  112. - **A password is used once and never kept.** The sign-in page takes an Immich email and
  113. password, signs in to Immich, creates a read-only API key named `Immich MCP (<app> · <id>)`,
  114. signs out and drops the password. It is not stored, logged or put in a token. Signing in again
  115. from the same app replaces that key; another app's key, or the same app on another computer,
  116. is never touched. Five wrong passwords make an account wait 15 minutes on this page (not in
  117. Immich). Anyone who knows an email can trigger that wait; pasting a key still works meanwhile.
  118. - **Or no password at all.** The page also accepts a pasted API key, and
  119. `IMMICH_MCP_PASSWORD_SIGN_IN=false` leaves that as the only way in. A pasted key that can do
  120. more than read is refused, as is one missing `asset.read`, `asset.view`, `person.read` or
  121. `album.read`.
  122. - **Only known clients can connect.** Redirect URIs are limited to Claude's callbacks, loopback
  123. (desktop and CLI clients) and `IMMICH_MCP_OAUTH_REDIRECT_URIS`. Otherwise anyone could register
  124. a client and send a family member a link to the real sign-in page. Another hosted client is
  125. refused at registration with `invalid_redirect_uri` until its callback is added there.
  126. - **Tell the family: only sign in on a page you opened yourself**, from your own app, just now.
  127. A link to the sign-in page sent by someone else connects *their* app to your photos.
  128. - **Nothing is stored.** A token is the person's API key sealed with `IMMICH_MCP_SECRET`
  129. (AES-256-GCM), valid for one hour and refreshed for up to 90 days at a time; after a year the
  130. key is pasted again. Keep the secret out of the repository and make it random
  131. (`openssl rand -base64 48`); whoever holds it and a token holds that read-only key.
  132. - **To disconnect someone, delete their key in Immich.** There is no revocation here: the key
  133. stops working in Immich at once, and the client is asked to sign in again at the next refresh.
  134. - **Run it behind a reverse proxy that sets `X-Forwarded-For`** and rate-limits `/authorize`,
  135. `/token` and `/register`. Key checks are budgeted per client address (10 a minute) and in total
  136. (60 a minute); without a proxy only the total applies.
  137. - Each person's calls run with their own key, so Immich enforces what they can see, and album and
  138. place names are cached per key.
  139. ## Protocol
  140. Streamable HTTP at `/mcp` (health at `/healthz`), or stdio. Clients on protocol revision
  141. 2026-07-28 are served statelessly, one request at a time; 2025-era clients get a session
  142. (`Mcp-Session-Id`, closed after 30 minutes idle).
  143. ## Development
  144. ```bash
  145. npm ci
  146. npm test && npm run lint && npm run typecheck && npm run build
  147. ```
  148. See [CLAUDE.md](CLAUDE.md) for the architecture and conventions, and
  149. [docs/design.md](docs/design.md) for the decisions behind the tool set.
  150. ## License
  151. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.