94 lines
2.3 KiB
Markdown
94 lines
2.3 KiB
Markdown
# 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.
|