Skip to main content
Glama

immich-mcp (Immich MCP connector)

MCP connector for a self-hosted Immich instance. It speaks the Immich REST API over stdio and over stateless Streamable HTTP on localhost.

Immich is AGPL-3.0 software. This connector is MIT. It only calls the public REST API on the server you configure. It is not affiliated with Immich or the Immich maintainers. Bring your own API key from the Immich user settings.

The connector covers all 199 paths and 287 operations in immich.openapi.json (Immich 3.3.0-rc.0). Operations are grouped into 22 toolsets. Enable a subset with IMMICH_TOOLSETS so the model only sees the tools you need.

Setup

npm install
npm run ci
npm start
npm run start:http

npm start speaks stdio. npm run start:http serves Streamable HTTP at http://127.0.0.1:3000/mcp and GET /health. HTTP mode has no authentication. Keep it on localhost.

Create an API key in Immich (Account settings, API Keys). The connector sends it as x-api-key and never prints it.

{
  "mcpServers": {
    "immich": {
      "command": "node",
      "args": ["/workspace/connectors/immich/dist/index.js"],
      "env": {
        "IMMICH_URL": "https://photos.example.com",
        "IMMICH_API_KEY": "...",
        "IMMICH_ALLOW_WRITES": "false",
        "IMMICH_TOOLSETS": "assets,albums,people,search,server",
        "IMMICH_CONTACT": "you@example.com"
      }
    }
  }
}

A trailing /api on IMMICH_URL is stripped. The API is called at {IMMICH_URL}/api.

Docker (HTTP, no authentication, localhost only):

docker build -t immich-mcp .
docker run -p 3000:3000 \
  -e IMMICH_URL=http://host.docker.internal:2283 \
  -e IMMICH_API_KEY=... \
  immich-mcp

Do not put the API key in the image.

Regenerate the operations registry after an OpenAPI bump:

npm run gen:operations

Related MCP server: seafile-mcp

Config

Variable

Meaning

IMMICH_URL

Server base, for example https://photos.example.com. /api is appended.

IMMICH_API_KEY

API key. Sent as x-api-key.

IMMICH_ALLOW_WRITES

Must be the literal true before a confirmed write is sent.

IMMICH_TOOLSETS

Comma list of toolsets, or all. Default assets,albums,people,search,server. admin is opt-in.

IMMICH_PER_MINUTE

Local request budget. Default 30.

IMMICH_TIMEOUT_MS

Upstream timeout. Default 20000.

IMMICH_CACHE_TTL_SEC

GET cache TTL. Default 60. Writes clear the cache.

IMMICH_CONTACT

Contact token in the User-Agent.

MCP_TRANSPORT

stdio or http. --http overrides.

PORT

HTTP port. Default 3000.

Safety

Every non-GET operation is gated unless the registry marks it read-only. Search metadata, smart search, random search, bulk-upload check, download info, and a few other POST reads are read-only. They run without confirm.

A write needs confirm: true and IMMICH_ALLOW_WRITES=true. Otherwise the tool returns a dry-run preview of the exact method, path, query, and body. The API key is redacted. Deletes, empty trash, user deletion, library scan or removal, API-key and session revoke, shared-link creation, and admin config changes add extra warnings in that preview.

Asset upload is multipart from a local file_path and is confirm-gated. Original and thumbnail downloads return metadata only, or write bytes to save_path. Binaries are not dumped into the model context. Server filesystem paths, tokens, passwords, and shared-link keys are stripped or redacted.

Tools

Default IMMICH_TOOLSETS publishes 5 tools (107 operations). IMMICH_TOOLSETS=all publishes 22 tools (287 operations). Each tool takes action plus params, query, body, and optional file_path, save_path, and confirm.

Toolset

Tool

Operations

Tags

Default

assets

immich_assets

43

Assets, Asset files, Download, Duplicates, Stacks

yes

albums

immich_albums

13

Albums

yes

people

immich_people

19

People, Faces

yes

search

immich_search

16

Search, Map, Timeline, Views

yes

server

immich_server

16

Server, Config (public)

yes

admin

immich_admin

40

Users (admin), Maintenance (admin), Config (admin), Database Backups (admin), Notifications (admin), Authentication (admin), System config, System metadata

no

users

immich_users

18

Users, Config (user)

no

sessions

immich_sessions

31

Sessions, Authentication, Passkeys

no

libraries

immich_libraries

8

Libraries

no

tags

immich_tags

9

Tags

no

trash

immich_trash

3

Trash

no

memories

immich_memories

8

Memories

no

jobs

immich_jobs

8

Jobs, Queues

no

shared-links

immich_shared_links

9

Shared links

no

api-keys

immich_api_keys

7

API keys

no

partners

immich_partners

5

Partners

no

activities

immich_activities

4

Activities

no

notifications

immich_notifications

6

Notifications

no

sync

immich_sync

4

Sync

no

plugins

immich_plugins

4

Plugins

no

workflows

immich_workflows

8

Workflows

no

cluster-groups

immich_cluster_groups

8

Cluster groups

no

Example. List albums, then create one after previewing:

{ "action": "get_all_albums" }
{ "action": "create_album", "body": { "albumName": "Trip" } }
{ "action": "create_album", "body": { "albumName": "Trip" }, "confirm": true }

Live check

npm run live-check talks to a real Immich when IMMICH_URL and IMMICH_API_KEY are set. It exercises read tools and confirm-gated create, modify and delete cycles for albums, tags, assets (upload, download, update, delete), memories, shared links and API keys. If those variables are unset, it prints a skip message and exits 0.

LIVE-CHECK.md records the real run (Immich v3.3.0-rc.0 built from source on the box, failed=0) and lists what was not exercised live.

License

MIT, see LICENSE. This is an independent, unofficial connector and is not endorsed by the Immich project or its owners.

The upstream immich.openapi.json comes from a AGPL-3.0 project, so it is not shipped here. src/operations.ts was generated from it, and tests fall back to a route-only fixture in test/fixtures/. To regenerate, download the spec from the upstream project into the repo root (it is gitignored) and run node scripts/gen-operations.mjs.

Available Tools

5 tools
immich_albumsA
DestructiveIdempotent

immich_albums covers the albums toolset (13 operations). Auth header x-api-key. Writes need confirm:true and IMMICH_ALLOW_WRITES=true. Omit confirm for a dry-run preview. Actions: add_assets_to_album: PUT /albums/{id}/assets. Add assets to an album add_assets_to_albums: PUT /albums/assets. Add assets to albums add_users_to_album: PUT /albums/{id}/users. Share album with users create_album: POST /albums. Create an album delete_album: DELETE /albums/{id}. Delete an album get_album_info: GET /albums/{id}. Retrieve an album get_album_map_markers: GET /albums/{id}/map-markers. Retrieve album map markers get_album_statistics: GET /albums/statistics. Retrieve album statistics get_all_albums: GET /albums. List all albums remove_asset_from_album: DELETE /albums/{id}/assets. Remove assets from an album remove_user_from_album: DELETE /albums/{id}/user/{userId}. Remove user from album update_album_info: PATCH /albums/{id}. Update an album update_album_user: PUT /albums/{id}/user/{userId}. Update user role

Inputs: action (required), body, query, params, +5 more.

immich_assetsA
DestructiveIdempotent

immich_assets covers the assets toolset (43 operations). Auth header x-api-key. Writes need confirm:true and IMMICH_ALLOW_WRITES=true. Omit confirm for a dry-run preview. Actions: check_bulk_upload: POST /assets/bulk-upload-check. Check bulk upload copy_asset: PUT /assets/copy. Copy asset create_stack: POST /stacks. Create a stack delete_asset_file: DELETE /asset-files/{id}. Delete an asset file delete_asset_metadata: DELETE /assets/{id}/metadata/{key}. Delete asset metadata by key delete_assets: DELETE /assets. Delete assets delete_bulk_asset_metadata: DELETE /assets/metadata. Delete asset metadata delete_duplicate: DELETE /duplicates/{id}. Dismiss a duplicate group delete_duplicates: DELETE /duplicates. Delete duplicates delete_stack: DELETE /stacks/{id}. Delete a stack delete_stacks: DELETE /stacks. Delete stacks download_archive: POST /download/archive. Download asset archive download_asset: GET /assets/{id}/original. Download original asset download_asset_file: GET /asset-files/{id}/download. Download an asset file edit_asset: PUT /assets/{id}/edits. Apply edits to an existing asset end_session: DELETE /assets/{id}/video/stream/{sessionId}. End HLS streaming session get_asset_duplicates: GET /duplicates. Retrieve duplicates get_asset_edits: GET /assets/{id}/edits. Retrieve edits for an existing asset get_asset_file: GET /asset-files/{id}. Retrieve an asset file get_asset_info: GET /assets/{id}. Retrieve an asset get_asset_metadata: GET /assets/{id}/metadata. Get asset metadata get_asset_metadata_by_key: GET /assets/{id}/metadata/{key}. Retrieve asset metadata by key get_asset_ocr: GET /assets/{id}/ocr. Retrieve asset OCR data get_asset_statistics: GET /assets/statistics. Get asset statistics get_download_info: POST /download/info. Retrieve download information get_main_playlist: GET /assets/{id}/video/stream/main.m3u8. Get HLS main playlist get_media_playlist: GET /assets/{id}/video/stream/{sessionId}/{variantIndex}/playlist.m3u8. Get HLS media playlist get_segment: GET /assets/{id}/video/stream/{sessionId}/{variantIndex}/{filename}. Get HLS segment or init file get_stack: GET /stacks/{id}. Retrieve a stack play_asset_video: GET /assets/{id}/video/playback. Play asset video remove_asset_edits: DELETE /assets/{id}/edits. Remove edits from an existing asset remove_asset_from_stack: DELETE /stacks/{id}/assets/{assetId}. Remove an asset from a stack resolve_duplicates: POST /duplicates/resolve. Resolve duplicate groups run_asset_jobs: POST /assets/jobs. Run an asset job search_asset_files: GET /asset-files. Search asset files search_stacks: GET /stacks. Retrieve stacks update_asset: PUT /assets/{id}. Update an asset update_asset_metadata: PUT /assets/{id}/metadata. Update asset metadata update_assets: PUT /assets. Update assets update_bulk_asset_metadata: PUT /assets/metadata. Upsert asset metadata update_stack: PUT /stacks/{id}. Update a stack upload_asset: POST /assets. Upload asset view_asset: GET /assets/{id}/thumbnail. View asset thumbnail

Inputs: action (required), body, query, params, +5 more.

immich_peopleA
DestructiveIdempotent

immich_people covers the people toolset (19 operations). Auth header x-api-key. Writes need confirm:true and IMMICH_ALLOW_WRITES=true. Omit confirm for a dry-run preview. Actions: create_face: POST /faces. Create a face create_person: POST /people. Create a person delete_face: DELETE /faces/{id}. Delete a face delete_people: DELETE /people. Delete people delete_person: DELETE /people/{id}. Delete person get_all_people: GET /people. Get all people get_faces: GET /faces. Retrieve faces for asset get_person: GET /people/{id}. Get a person get_person_statistics: GET /people/{id}/statistics. Get person statistics get_person_thumbnail: GET /people/{id}/thumbnail. Get person thumbnail get_users_for_people: GET /people/users. Get people access merge_people: POST /people/merge. Merge people merge_person_legacy: POST /people/{id}/merge. Merge people reassign_faces: PUT /people/{id}/reassign. Reassign faces reassign_faces_by_id: PUT /faces/{id}. Re-assign a face to another person remove_users_from_people: DELETE /people/users. Remove users from people update_people: PUT /people. Update people update_person: PUT /people/{id}. Update person upsert_people_users: PUT /people/users. Upsert user access

Inputs: action (required), body, query, params, +5 more.

immich_serverA
DestructiveIdempotent

immich_server covers the server toolset (16 operations). Auth header x-api-key. Writes need confirm:true and IMMICH_ALLOW_WRITES=true. Omit confirm for a dry-run preview. Actions: delete_server_license: DELETE /server/license. Delete server product key get_about_info: GET /server/about. Get server information get_apk_links: GET /server/apk-links. Get APK links get_public_config: GET /public/config. Get the public configuration get_public_config_defaults: GET /public/config/defaults. Get the public configuration defaults get_server_config: GET /server/config. Get config get_server_features: GET /server/features. Get features get_server_license: GET /server/license. Get product key get_server_statistics: GET /server/statistics. Get statistics get_server_version: GET /server/version. Get server version get_storage: GET /server/storage. Get storage get_supported_media_types: GET /server/media-types. Get supported media types get_version_check: GET /server/version-check. Get version check status get_version_history: GET /server/version-history. Get version history ping_server: GET /server/ping. Ping set_server_license: PUT /server/license. Set server product key

Inputs: action (required), body, query, params, +5 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 5 tools

    Disambiguation4/5

    The five tools are split along clear domain lines (albums, assets, people, search, server), so an agent can generally pick the right tool. However, boundaries blur at the edges: search_asset_statistics vs get_asset_statistics, get_map_markers vs get_album_map_markers, and search_person vs get_all_people create cross-tool overlap, and each tool multiplexes 13-43 actions behind one name, so action-level selection still requires careful reading.

    Naming Consistency5/5

    Every tool uses the same immich_<domain> snake_case pattern, and the embedded action names inside each tool follow a consistent verb_noun convention (get_album_info, create_album, delete_album). No camelCase or mixed-verb anomalies anywhere in the surface.

    Tool Count4/5

    Five tools is a reasonable, well-scoped count for an Immich API wrapper and keeps the top-level list small. The trade-off is that immich_assets alone bundles 43 operations, making individual tools quite heavy compared to the 3-15 tool ideal.

    Completeness4/5

    Core domains of the Immich API are covered end-to-end: albums, assets, people/faces, search/timeline, and server config/licensing. Entire areas such as tags, memories, shared links, activities, and user/admin management are absent, but these are secondary to the primary photo-library workflows.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      C
      maintenance
      It exposes the full official Immich API (276 tools across 41 groups) to MCP clients, letting them search and manage assets, albums, people, tags, memories, shared links, users, jobs and admin settings. It supports file uploads and downloads, stdio or streamable HTTP transports, and filtering/read-only safety modes.
      276
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Connects MCP clients to a self-hosted Seafile server through the seahub HTTP API, exposing libraries, files, search, sharing, and optional admin operations over stdio or Streamable HTTP. It defaults to read-focused tools and gates writes behind confirmation, with token redaction and dry-run previews.
      4
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables MCP clients to interact with a self-hosted comic/library server through its HTTP API, exposing libraries, series, books, collections, readlists, metadata, and administrative operations with read/write safety controls over stdio or Streamable HTTP.
      7
      MIT