Immich MCP Server

Предоставляет доступ к вашей библиотеке фото Immich для ChatGPT (и любого другого MCP-клиента) через Streamable HTTP, чтобы вы могли задавать вопросы вроде "найди фотографии с посещения площадки в Кигали в марте" и получать реальные ответы с вашего собственного NAS.

ChatGPT  ──HTTPS──▶  Cloudflare Tunnel  ──▶  immich_mcp:8080  ──▶  immich_server:2283
          bearer token                        MCP → REST            x-api-key

Почему это сделано так

Пользовательские коннекторы ChatGPT принимают только удаленный HTTPS-эндпоинт. Нет опции stdio или localhost, поэтому сервер должен быть доступен из интернета — отсюда туннель — и должен защищать себя, отсюда токен-носитель.

Инструменты

search и fetch названы намеренно: режим Deep Research от ChatGPT игнорирует все остальные инструменты, поэтому эти два берут на себя нагрузку, если режим разработчика недоступен.

Настройка

1. Получите API-ключ Immich

Immich → Настройки учетной записи → API-ключи → Новый API-ключ. Ограничьте его только чтением, если не планируете включать ссылки для общего доступа.

2. Настройте

cp .env.example .env
openssl rand -hex 32          # paste into MCP_BEARER_TOKEN
$EDITOR .env

Найдите сеть Docker, в которой уже работает Immich, и укажите ее имя в docker-compose.yml в разделе networks.immich-net.name:

docker network ls | grep -i immich

Обычно это immich_default. Если контейнер MCP не может к ней подключиться, установите IMMICH_URL на LAN-адрес NAS (http://192.168.1.50:2283) и удалите блок networks:.

3. Соберите и запустите

docker compose up -d --build
docker compose logs -f immich-mcp

Проверьте локально, прежде чем открывать доступ:

curl http://127.0.0.1:8099/healthz
# {"status":"ok","immich":{"major":1,"minor":...}}

pip install httpx
python smoke_test.py http://127.0.0.1:8099 <your-bearer-token>

Смок-тест выполняет то же рукопожатие, что и ChatGPT — инициализация, tools/list, затем вызов реального инструмента — и подтверждает, что неаутентифицированные запросы получают 401.

4. Откройте доступ через Cloudflare Tunnel

Добавьте публичное имя хоста в ваш существующий туннель, указывающий на http://immich_mcp:8080. См. cloudflared/config.example.yml. Если вы управляете туннелем из панели Zero Trust, добавьте его туда.

Не ставьте Cloudflare Access перед этим именем хоста. ChatGPT не сможет завершить интерактивный вход через Access.

Повторно запустите смок-тест для публичного URL:

python smoke_test.py https://immich-mcp.example.com <your-bearer-token>

5. Подключите ChatGPT

Настройки → Коннекторы → Расширенные настройки → включите Режим разработчика (требуется платный план), затем создайте:

• Имя: Immich Photos

• Описание: это важно — модель читает его, чтобы решить, вызывать ли коннектор. Что-то вроде "Личная библиотека фото и видео. Используется для поиска, описания или просмотра списка фотографий, альбомов и распознанных людей."

• URL: https://immich-mcp.example.com/mcp

• Аутентификация: API-ключ / пользовательский заголовок → Authorization: Bearer <token>

Затем включите коннектор в компоновщике чата.

Заметки из реального использования

Называйте инструмент в своем запросе. ChatGPT не будет надежно угадывать, когда обращаться к пользовательскому коннектору. "Используй immich search, чтобы найти фотографии сушильных стеллажей" работает, а "найди мои фото сушильных стеллажей" — часто нет.

ChatGPT не видит ваши фотографии. Результаты работы инструментов — это текст — описания и метаданные, а не пиксели. create_share_link существует, чтобы преодолеть этот разрыв, но ссылка для общего доступа является публичной для любого, у кого есть URL, поэтому она отключена по умолчанию. Включайте ее, только если вас это устраивает.

Зафиксируйте версию Immich. API меняется между релизами — /server/statistics не так давно было /server-info/statistics. Ваш собственный экземпляр публикует точную спецификацию по адресу https://photos.example.com/api/docs; проверяйте там, прежде чем отлаживать 404.

Ротируйте токен-носитель, отредактировав .env и выполнив docker compose up -d --force-recreate, затем обновив коннектор в ChatGPT.

Устранение неполадок