hermes-skills/skills/devops/mcp-servers/references/immich-photo-map-mcp.md

Immich photo map MCP pattern

Use this when Germaine asks to extract photo metadata from Immich and show where photos were taken.

Immich API endpoints

Relevant stable endpoints:

• POST /search/metadata with withExif: true to search assets and include EXIF/location data.
• GET /assets/{id}/metadata to fetch full key-value metadata for a single asset.

/search/metadata can filter by album IDs, taken date, city/state/country, camera make/model, favorite state, asset type, etc.

Recommended MCP tools

• immich_search_geo_assets(taken_after?, taken_before?, album_id?, limit=500) — return assets with latitude/longitude, taken time, filename, city/state/country, camera model, thumbnail URL.
• immich_get_asset_metadata(asset_id) — return full Immich metadata for one asset.
• immich_geojson(...) — return a GeoJSON FeatureCollection suitable for Leaflet/MapLibre.
• immich_map_summary(...) — summarize counts by city/country/date range and count missing-location assets.

Map UI

The MCP should return data; a small UI can live in ops portal or a private subdomain. Use Leaflet + OpenStreetMap tiles + marker clustering. Marker click should show thumbnail, filename, taken date, and location labels.

Security

GPS photo data is sensitive. Keep the MCP localhost-only, store IMMICH_BASE_URL and IMMICH_API_KEY in a chmod 600 .env, and put any map UI behind auth/Cloudflare Access. Prefer thumbnails, not full-resolution assets.

Implementation notes

• Count missing GPS as missing_location, not an error.
• Return GeoJSON coordinates as [longitude, latitude].
• Build read-only first. Metadata update/fix workflows are a later explicit feature.