59 lines
2.2 KiB
Markdown
59 lines
2.2 KiB
Markdown
# 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)
|