Skip to main content
Glama
Sign In
immich-mcp

immich-mcp

by si-essence
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

immich_assets

DestructiveIdempotent

Manage Immich photo and video assets through 43 operations for upload, download, search, edits, stacks, duplicates, metadata, and statistics; writes require confirmation.

Instructions

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

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "action": "<action>"
    },
    "name": "immich_assets"
  }
}

Input Schema

NameRequiredDescriptionDefault
bodyNoJSON body for the Immich operation. Secrets are redacted in output.
queryNoOpenAPI query parameters.
actionYesImmich operation to call.
paramsNoOpenAPI path parameters, such as id.
confirmNoSet to the boolean true to execute the write. Omit this field for a dry-run preview. false and the string true are rejected.
checksumNoOptional x-immich-checksum header for asset upload.
file_pathNoLocal file to upload as multipart assetData. Confirm-gated. The path is omitted from output.
save_pathNoLocal path to save a binary download. If omitted, only metadata is returned. The path is omitted from output.
sidecar_pathNoOptional local XMP sidecar for asset upload. The path is omitted from output.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already flag destructive, open-world, idempotent, and non-read-only behavior. The description adds auth header requirements, the write confirmation environment gate, dry-run preview, and output redaction of secrets and local file paths, which materially helps safe invocation. It does not cover per-action reversibility or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The front-loaded auth and write rules are useful, but the 43-action list is long and repetitive, restating action names and endpoints in a dense paragraph. A more compact action reference would preserve the information with less redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a multiplexed tool with 43 operations, the description covers auth, write safety, dry-run behavior, and the full action inventory. Remaining gaps include return-shape guidance and per-action parameter applicability, but annotations and schema carry much of that burden.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so all nine parameters are already documented. The description adds action-to-endpoint mappings and the confirm/environment requirement beyond the enum labels, though it does not explain how body, query, and path parameters vary by action.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names the assets toolset and enumerates all 43 actions with HTTP endpoints, so the resource domain is clear. However, it does not explicitly distinguish immich_assets from siblings such as immich_search or immich_albums.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explains the write gate (confirm:true plus IMMICH_ALLOW_WRITES=true) and dry-run behavior, which is important usage context. It does not say when to choose this tool over sibling tools or how to route overlapping search operations.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools