Immich MCP Server

Exposes a self-hosted Immich photo library to ChatGPT (and any other MCP client) over Streamable HTTP, so you can ask questions like "find the photos from the Kigali site visit in March" and get real answers from your own NAS.

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

이렇게 구축한 이유

ChatGPT 사용자 지정 커넥터는 원격 HTTPS 엔드포인트만 허용합니다. stdio나 localhost 옵션은 없으므로 서버는 인터넷에서 접근 가능해야 하며(따라서 터널), 스스로를 방어해야 하므로(따라서 베어러 토큰)입니다.

도구들

search와 fetch는 의도적으로 이름이 지어졌습니다: ChatGPT의 Deep Research 모드는 다른 모든 도구를 무시하므로, 개발자 모드를 사용할 수 없을 때 이 두 도구가 부담을 담당합니다.

설정

1. Immich API 키 얻기

Immich → 계정 설정 → API 키 → 새 API 키. 공유 링크를 활성화할 계획이 없다면 읽기 전용으로 범위를 지정하세요.

2. 구성

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

Immich가 이미 실행 중인 Docker 네트워크를 찾아 docker-compose.yml의 networks.immich-net.name 아래에 그 이름을 입력하세요:

docker network ls | grep -i immich

보통 immich_default입니다. MCP 컨테이너가 연결할 수 없으면 IMMICH_URL을 NAS LAN 주소(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는 사용자 지정 커넥터를 사용해야 할 때를 안정적으로 추측하지 못합니다. "Use immich search to find photos of the drying racks"는 작동하지만 "find my drying rack photos"는 종종 작동하지 않습니다.

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에서 커넥터를 업데이트하세요.

문제 해결