immich-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| PORT | No | HTTP port used when running in HTTP mode. | 3000 |
| IMMICH_URL | Yes | Immich server base URL, for example https://photos.example.com. /api is appended automatically. | |
| MCP_TRANSPORT | No | Transport to use: stdio or http. --http overrides this. | stdio |
| IMMICH_API_KEY | Yes | Immich API key from user settings. Sent as x-api-key and never printed. | |
| IMMICH_CONTACT | No | Contact token included in the User-Agent. | |
| IMMICH_TOOLSETS | No | Comma-separated list of toolsets to enable, or all. admin is opt-in. | assets,albums,people,search,server |
| IMMICH_PER_MINUTE | No | Local request budget per minute. | 30 |
| IMMICH_TIMEOUT_MS | No | Upstream request timeout in milliseconds. | 20000 |
| IMMICH_ALLOW_WRITES | No | Must be the literal true before a confirmed write is sent. Otherwise writes return a dry-run preview. | false |
| IMMICH_CACHE_TTL_SEC | No | GET cache TTL in seconds. Writes clear the cache. | 60 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| immich_albumsA | 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 |
| immich_assetsA | 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 |
| immich_peopleA | 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 |
| immich_searchC | 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 |
| immich_serverA | 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 |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
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.