immich-mcp

Active

Immich photo library.

GitHub repo → npm: immich-mcp →
~55
MCP tools
11
domains
stdio
transport
MIT
license

WHAT IT DOES

immich-mcp is a Model Context Protocol server for Immich. Point an MCP-compatible client at it and your photo and video library becomes a set of tools the agent can call: browse and search assets, manage albums and tags, recognize and merge people, surface memories, resolve duplicates, and group motion photos into stacks, all as typed tool calls.

It exposes roughly 55 tools across 11 domains, with memories, duplicates, and stacks supported out of the box. Search covers CLIP / semantic queries (immich_search_smart) plus structured metadata search and the discovery "explore" feed.

Two-tier write protection keeps the library safe: all writes are gated behind the IMMICH_ALLOW_WRITES=true env var, and destructive tools additionally require confirm: true on each call. Reads always work. Path-based uploads are confined to an opt-in IMMICH_UPLOAD_BASE_DIR.

INSTALL

Published to npm. Install globally to get the immich-mcp binary, or build from source. Requires Node.js 20+ and an Immich server with API access.

$ npm install -g immich-mcp # install the server binary
 
# or from source
$ git clone https://github.com/lidless-labs/immich-mcp.git
$ cd immich-mcp && npm install && npm run build

Configure with IMMICH_BASE_URL (note the /api suffix) and IMMICH_API_KEY (Account Settings › API Keys). Set IMMICH_ALLOW_WRITES=true to expose write and delete tools; IMMICH_UPLOAD_BASE_DIR to allow path-based uploads; IMMICH_VERIFY_SSL=false only for self-signed certs (scoped to the Immich client alone).

CLIENT CONFIG

A sample mcpServers entry (Claude Desktop, or any MCP client that reads the same shape). It runs the installed binary over stdio. Leave IMMICH_ALLOW_WRITES at "false" until you want write tools. 

{
  "mcpServers": {
    "immich-mcp": {
      "command": "immich-mcp",
      "env": {
        "IMMICH_BASE_URL": "https://photos.example.com/api",
        "IMMICH_API_KEY": "YOUR_KEY",
        "IMMICH_ALLOW_WRITES": "false"
      }
    }
  }
}

For Claude Code use claude mcp add immich-mcp -e IMMICH_BASE_URL=... -e IMMICH_API_KEY=... -e IMMICH_ALLOW_WRITES=false -- immich-mcp. The README also documents OpenClaw, Codex CLI, and Hermes Agent, including source-checkout variants.

CAPABILITIES / TOOLS EXPOSED

Roughly 55 MCP tools across 11 domains. Grouped below; see the README for the full per-argument reference.

System (5)

immich_ping / immich_get_server_info
Health check plus version, build, and features.
get_server_statistics / get_storage / get_capabilities
Photo and video counts, disk usage and free space, and exposed feature flags.

Assets (11)

list_assets / get_asset / get_asset_exif / get_asset_statistics
Paginated filtered listing, full metadata, EXIF block, and per-library counts.
update_asset / bulk_update_assets
Rename, favorite, archive, set description; bulk updates require confirm: true.
delete_asset / restore_from_trash
Soft delete to trash by default (permanent delete requires confirm: true), and undo.
download_original / download_thumbnail / upload_from_path
Return original or preview bytes; upload is confined to IMMICH_UPLOAD_BASE_DIR.

Search (3)

immich_search_smart
CLIP / semantic search by natural-language query.
immich_search_metadata
Structured search by date range, camera make, location, and more.
immich_search_explore
Server-side discovery feed (cities, people, things).

Albums (8) & tags (7)

albums: list / get / statistics / create / update / add / remove / delete
Full album lifecycle; delete_album requires confirm: true.
tags: list / get / create / update / delete / add-to / remove-from
Manage tags and apply them to assets; delete_tag requires confirm: true.

People (6)

list_people / get_person / get_person_assets
Enumerate faces and the photos and videos each appears in.
update_person / hide_person / merge_people
Rename, set birth date or thumbnail, hide from discovery, and fold duplicate clusters (merge requires confirm: true).

Shared links, activities, memories, duplicates & stacks

shared_links + activities
Create, read, update, and delete shared links and shared-album comments/likes (deletes require confirm: true).
list_memories / get_memory
"On this day" and other generated memories.
list_duplicates / resolve_duplicates
Surface duplicate clusters, then pick a keeper and trash the rest (resolve requires confirm: true).
stacks: list / create / update / delete
Group motion photos, bracketed shots, and RAW+JPEG pairs (delete requires confirm: true).