Immich photo map MCP pattern

Use case

Build a read-only Immich MCP that extracts asset metadata and exposes geotagged photos as structured data for maps and summaries.

Immich endpoints

Useful Immich API endpoints:

POST /search/metadata
GET  /assets/{id}/metadata

For asset searches, request EXIF in results:

{
  "withExif": true,
  "size": 500,
  "takenAfter": "2026-01-01T00:00:00Z",
  "takenBefore": "2026-12-31T23:59:59Z"
}

MCP tool shape

Recommended tools:

immich_search_geo_assets(taken_after, taken_before, album_id=None, limit=500) — returns assets with latitude/longitude, taken date, location labels, camera info, and thumbnail URL.
immich_get_asset_metadata(asset_id) — returns full metadata for one asset.
immich_geojson(...) — returns a GeoJSON FeatureCollection for Leaflet/OpenStreetMap.
immich_map_summary(...) — returns top locations, missing-GPS count, and date-range summary.

Output contracts

Asset record:

{
  "id": "asset-uuid",
  "filename": "IMG_1234.jpeg",
  "taken_at": "2026-07-14T10:31:00",
  "latitude": 32.0809,
  "longitude": -81.0912,
  "city": "Savannah",
  "state": "Georgia",
  "country": "United States",
  "camera_make": "Apple",
  "camera_model": "iPhone 15 Pro",
  "thumb_url": "/api/assets/{id}/thumbnail"
}

GeoJSON feature:

{
  "type": "Feature",
  "geometry": {"type": "Point", "coordinates": [-81.0912, 32.0809]},
  "properties": {"asset_id": "uuid", "filename": "IMG_1234.jpeg", "taken_at": "..."}
}

Map UI

The MCP provides data; the web UI can be Leaflet.js with OpenStreetMap tiles, marker clustering, album/date filters, and thumbnail popups.

Recommended internal paths:

ops.itpropartner.com/immich-map.html
or
photos.itpropartner.com/map

Security notes

Photo GPS data is sensitive.

Keep MCP localhost-only.
Store IMMICH_BASE_URL and IMMICH_API_KEY in a chmod 600 .env / systemd EnvironmentFile.
Put any map UI behind existing auth/Cloudflare Access.
Prefer thumbnails over full-resolution images.
Count missing GPS as missing_location, not as errors.

Build order

Read-only MCP first: search, metadata, GeoJSON, summaries.
Verify against a small date range.
Build map UI.
Only later consider metadata update/fix tools.

2.3 KiB Raw Permalink Blame History