# Immich MCP Server — ITPP Reference

## Built: 2026-07-15

## Location
- Server: `/root/docker/immich-mcp/server.py`
- Service: `/tmp/immich-mcp.service` (pending install)
- Port: 8904
- Venv: `/opt/ops-portal/venv` (shared, contains fastmcp)
- Tools: 6 (immich_search, immich_asset_metadata, immich_map, immich_albums, immich_stats, immich_duplicates)

## Prerequisites (before deployment)
- [ ] `IMMICH_BASE_URL` in `/root/.hermes/.env` — URL of Immich server
- [ ] `IMMICH_API_KEY` in `/root/.hermes/.env` — generated in Immich → Account Settings → API Keys

## Deployment steps
```bash
cp /tmp/immich-mcp.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable --now immich-mcp

# Wire into Hermes
hermes config set mcp_servers.immich.url 'http://127.0.0.1:8904/mcp'
hermes config set mcp_servers.immich.enabled 'true'
hermes mcp test immich
```

## Immich API reference
- Auth: `x-api-key` header
- Base: `{IMMICH_BASE_URL}/api`
- Key endpoints used:
  - `POST /search/metadata` — search by EXIF, GPS, date, camera, city, country
  - `GET /assets/{id}` — full asset info
  - `GET /assets/{id}/metadata` — EXIF metadata
  - `GET /assets/{id}/thumbnail` — thumbnail image
  - `GET /albums` — album list
  - `GET /assets/statistics` — server stats
  - `GET /duplicates` — duplicate detection

## S3 storage notes (Immich server side)
- Immich stores everything locally by default (`UPLOAD_LOCATION`)
- To use S3: mount bucket with `s3fs-fuse` at the upload location
  - Pros: unlimited storage, no local disk limits
  - Cons: FUSE latency, slow thumbnail/transcode, DB stays local
- Better approach: local SSD + nightly backup to S3 via cron
  ```bash
  # Backup Immich assets to S3
  aws s3 sync /path/to/immich/library s3://itpropartner-backups/immich/library/ --delete
  aws s3 sync /path/to/immich/upload s3://itpropartner-backups/immich/upload/ --delete
  # DB dump
  pg_dump immich | aws s3 cp - s3://itpropartner-backups/immich/db/daily.sql.gz
  ```
- Backup cadence: daily (photos don't change often enough for 15-min sync)

## Backup recommendations
- DB + library assets: daily, S3
- Full backup: weekly, separate bucket
- Test restore: monthly (spin up test Immich container, point at restored DB + library)