# 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.
