immich-mcp
Connects to a self-hosted Immich instance's REST API, providing tools across 22 toolsets (assets, albums, people, faces, search, server, admin, users, sessions, libraries, tags, trash, memories, jobs, shared links, API keys, partners, activities, notifications, sync, plugins, workflows, cluster groups) covering 287 operations for browsing, searching, uploading, and managing photos and videos, with write operations gated behind explicit confirmation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@immich-mcp search my photos for beach sunsets from last summer"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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:httpnpm 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-mcpDo not put the API key in the image.
Regenerate the operations registry after an OpenAPI bump:
npm run gen:operationsRelated MCP server: seafile-mcp
Config
Variable | Meaning |
| Server base, for example |
| API key. Sent as |
| Must be the literal |
| Comma list of toolsets, or |
| Local request budget. Default 30. |
| Upstream timeout. Default 20000. |
| GET cache TTL. Default 60. Writes clear the cache. |
| Contact token in the User-Agent. |
|
|
| 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 |
| 43 | Assets, Asset files, Download, Duplicates, Stacks | yes |
albums |
| 13 | Albums | yes |
people |
| 19 | People, Faces | yes |
search |
| 16 | Search, Map, Timeline, Views | yes |
server |
| 16 | Server, Config (public) | yes |
admin |
| 40 | Users (admin), Maintenance (admin), Config (admin), Database Backups (admin), Notifications (admin), Authentication (admin), System config, System metadata | no |
users |
| 18 | Users, Config (user) | no |
sessions |
| 31 | Sessions, Authentication, Passkeys | no |
libraries |
| 8 | Libraries | no |
tags |
| 9 | Tags | no |
trash |
| 3 | Trash | no |
memories |
| 8 | Memories | no |
jobs |
| 8 | Jobs, Queues | no |
shared-links |
| 9 | Shared links | no |
api-keys |
| 7 | API keys | no |
partners |
| 5 | Partners | no |
activities |
| 4 | Activities | no |
notifications |
| 6 | Notifications | no |
sync |
| 4 | Sync | no |
plugins |
| 4 | Plugins | no |
workflows |
| 8 | Workflows | no |
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 toolsimmich_albumsADestructiveIdempotent
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_assetsADestructiveIdempotent
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_peopleADestructiveIdempotent
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_searchCRead-only
immich_search covers the search toolset (16 operations). Auth header x-api-key. Actions: get_assets_by_city: GET /search/cities. Retrieve assets by city get_assets_by_original_path: GET /view/folder. Retrieve assets by original path get_explore_data: GET /search/explore. Retrieve explore data get_map_markers: GET /map/markers. Retrieve map markers get_search_suggestions: GET /search/suggestions. Retrieve search suggestions get_time_bucket: GET /timeline/bucket. Get time bucket get_time_buckets: GET /timeline/buckets. Get time buckets get_unique_original_paths: GET /view/folder/unique-paths. Retrieve unique paths reverse_geocode: GET /map/reverse-geocode. Reverse geocode coordinates search_asset_statistics: POST /search/statistics. Search asset statistics search_assets: POST /search/metadata. Search assets by metadata search_large_assets: POST /search/large-assets. Search large assets search_person: GET /search/person. Search people search_places: GET /search/places. Search places search_random: POST /search/random. Search random assets search_smart: POST /search/smart. Smart asset search
Inputs: action (required), body, query, params, +4 more.
immich_serverADestructiveIdempotent
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
Scored across 5 tools
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.
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.
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.
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
Related MCP Connectors
Read-only MCP server over the JENRIKS daily photoblog: one photo per day since 2006. No auth.
Browse, search, upload, tag, transfer, and delete images in your Raster libraries over MCP.
Remote MCP server for full read/write access to a Zotero library
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
Related MCP Servers
- AlicenseCqualityCmaintenanceIt 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.276MIT
- AlicenseBqualityBmaintenanceConnects 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.4MIT
- AlicenseAqualityCmaintenanceEnables 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.7MIT
- AlicenseCqualityBmaintenanceEnables MCP clients to manage a media library, review duplicate-cleanup galleries, run workflows, and create generations through a local server authenticated with the user's account.66MIT