Immich Photo Manager

What drolosoft/immich-photo-manager MCP server does

The drolosoft/immich-photo-manager MCP server gives an MCP-compatible assistant access to a self-hosted Immich library. It is intended for conversational photo-management tasks such as finding images, organizing albums, identifying duplicates, and reviewing library condition.

Search can use natural-language descriptions with CLIP, allowing requests based on visual concepts rather than only filenames or metadata. GPS information can be used to group photos geographically and create albums for trips or other places. Temporal matching is also used alongside location and visual information when building curated albums.

The project also supports duplicate discovery across sources using perceptual hashing. For review and sharing, it can produce interactive HTML galleries designed to work offline. Library health reports provide another way to inspect the state of an Immich collection.

How it works

The drolosoft/immich-photo-manager MCP server runs on the local machine and connects to one Immich instance at a time. The connection uses the Immich server URL and an Immich API key. Setup can validate the credentials against the server, save them for later sessions, and replace the active connection through a conversational request without editing a configuration file.

An MCP client invokes the server’s tools based on the user’s request. The project is described as providing MCP tools, skills, and slash commands for supported workflows. It is designed to work with Claude Code as a plugin and also exposes a plain MCP server for Claude Desktop, Cowork, and other MCP clients.

Setup and configuration

The documented prerequisites are a running self-hosted Immich instance, Immich v1.90 or newer, an Immich API key, and Python 3.10 or newer with pip. For a direct MCP-client setup, the README shows the uvx package entry point:

{
  "mcpServers": {
    "immich": {
      "command": "uvx",
      "args": ["immich-photo-manager"]
    }
  }
}

Claude Code users can instead clone the repository, install the dependencies from src/requirements.txt, add the local directory as a Claude plugin marketplace, and install the immich-photo-manager plugin. The /setup-immich-photo-manager command guides the user through the server URL and API key. Credentials can also be updated by stating the new URL and key in the conversation.

Tools and capabilities

The drolosoft/immich-photo-manager MCP server supports capabilities including:

• Natural-language and CLIP-based photo search.
• Geographic album creation using GPS data.
• Album organization using location, visual similarity, and time.
• Duplicate detection across sources with perceptual hashing.
• Library health reporting.
• Interactive HTML gallery generation for offline use.
• Photo inspection workflows that can use thumbnails or previews when requested.
• PDF report export to a local path, with optional base64 return.

These operations are useful for large libraries where manual sorting, trip grouping, or duplicate review would otherwise require separate scripts.

Limitations and notes

The server requires an accessible Immich instance and a valid API key; it is not a standalone photo library. Only one Immich connection is active at a time, although the connection can be switched by updating the credentials.

The process runs locally, but content read by the assistant may be sent to the model provider. This can include filenames, dates, EXIF data, album lists, and thumbnails or previews when image understanding is requested. Originals are not fetched. With a local model connected over MCP, the README states that this model traffic does not leave the local network.

PDF files are written to the machine running the server and are not sent elsewhere unless base64 output is requested. Map tiles for the Places page come from OpenStreetMap unless map output is disabled. The project is released under the MIT license.