Immich MCP Server

Expone una biblioteca de fotos autoalojada de Immich a ChatGPT (y a cualquier otro cliente MCP) a través de HTTP Streamable, para que puedas hacer preguntas como "encuentra las fotos de la visita al sitio de Kigali en marzo" y obtener respuestas reales de tu propio NAS.

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

Por qué está construido de esta manera

Los conectores personalizados de ChatGPT solo aceptan un endpoint HTTPS remoto. No hay opción stdio o localhost, por lo que el servidor debe ser accesible desde internet — de ahí el túnel — y debe defenderse, de ahí el token de portador.

Herramientas

search y fetch están nombrados deliberadamente: el modo de investigación profunda de ChatGPT ignora todas las demás herramientas, por lo que esas dos asumen la carga si el Modo Desarrollador no está disponible.

Configuración

1. Obtén una clave API de Immich

Immich → Configuración de la cuenta → Claves API → Nueva clave API. Limítala a solo lectura a menos que planees habilitar enlaces compartidos.

2. Configurar

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

Encuentra la red Docker en la que ya se ejecuta Immich y pon su nombre en docker-compose.yml bajo networks.immich-net.name:

docker network ls | grep -i immich

Normalmente es immich_default. Si el contenedor MCP no puede unirse a ella, configura IMMICH_URL con la dirección LAN del NAS en su lugar (http://192.168.1.50:2283) y elimina el bloque networks:.

3. Construir y ejecutar

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

Verifica localmente antes de exponer nada:

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>

La prueba de humo ejecuta el handshake exacto que hace ChatGPT — inicializar, tools/list, luego una llamada a herramienta en vivo — y confirma que las solicitudes no autenticadas reciben un 401.

4. Exponer a través de Cloudflare Tunnel

Añade un nombre de host público a tu túnel existente apuntando a http://immich_mcp:8080. Consulta cloudflared/config.example.yml. Si gestionas el túnel desde el panel de Zero Trust, agrégaselo allí.

No pongas Cloudflare Access delante de este nombre de host. ChatGPT no puede completar un inicio de sesión interactivo de Access.

Vuelve a ejecutar la prueba de humo contra la URL pública:

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

5. Conectar ChatGPT

Configuración → Conectores → Configuración avanzada → activa el Modo Desarrollador (requiere un plan de pago), luego Crear:

• Nombre: Immich Photos

• Descripción: esto importa — el modelo lo lee para decidir si invocar el conector. Algo como "Biblioteca personal de fotos y vídeos. Úsalo para encontrar, describir o listar fotos, álbumes y personas reconocidas."

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

• Autenticación: Clave API / encabezado personalizado → Authorization: Bearer <token>

Luego activa el conector en el compositor del chat.

Notas de uso real

Nombra la herramienta en tu prompt. ChatGPT no adivinará de manera fiable cuándo recurrir a un conector personalizado. "Usa immich search para encontrar fotos de los secadores" funciona, mientras que "encuentra mis fotos de los secadores" a menudo no.

ChatGPT no puede ver tus fotos. Los resultados de las herramientas son texto — descripciones y metadatos, no píxeles. create_share_link existe para cerrar esa brecha, pero un enlace compartido es público para cualquiera que tenga la URL, por lo que está desactivado por defecto. Actívalo solo si te sientes cómodo con eso.

Fija tu versión de Immich. La API cambia entre versiones — /server/statistics era /server-info/statistics no hace mucho. Tu propia instancia publica la especificación exacta en https://photos.example.com/api/docs; verifícalo allí antes de depurar un 404.

Rota el token de portador editando .env y ejecutando docker compose up -d --force-recreate, luego actualiza el conector en ChatGPT.

Solución de problemas