hermes-recovery/references/immich-mcp-reference.md

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

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

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