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

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

For asset searches, request EXIF in results:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

```text
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

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