Skip to main content
Glama

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 *.delete permission, so Immich itself refuses

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

view_photos returns the images so the model can actually look at them

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 camera

  • view_photos — returns up to 4 large (~1440 px) or 16 small (~250 px) images for the model to look at

  • get_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 text

  • list_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 as Parent/Child

People and faces

  • update_person — name, birth date, hidden, favorite

  • create_person, reassign_face — fix faces Immich assigned to the wrong person

  • merge_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_queues

  • admin_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

  1. The MCP client discovers the server through /.well-known/oauth-protected-resource/mcp and registers itself.

  2. You see a sign-in page on your own domain that names the app asking and says what it may do.

  3. 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.

  4. 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.

  5. 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: always

Route 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

PUBLIC_URL

(required)

Public URL of the MCP endpoint; also the OAuth issuer

IMMICH_URL

(required)

How this server reaches Immich

IMMICH_PUBLIC_URL

origin of PUBLIC_URL

Base for photo links in results

DATA_DIR

./data (/data in the image)

SQLite database and generated encryption key

ENCRYPTION_KEY

generated into DATA_DIR

Base64 32-byte key; set it to keep the key out of the data directory

ALLOWED_REDIRECT_URIS

Claude callbacks, loopback

Comma-separated; exact URIs or scheme://host:*

ACCESS_TOKEN_TTL, REFRESH_TOKEN_TTL

3600, 7776000

Seconds

TRUST_PROXY

loopback

Express trust proxy, for rate limits behind a proxy

API_KEY_NAME

Claude (immich-mcp)

Name of the key created in Immich

PORT, HOST

8080, 0.0.0.0

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 it

The 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

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables 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.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      1
      AGPL 3.0