Immich MCP Server

Stellt eine selbst gehostete Immich-Fotobibliothek für ChatGPT (und jeden anderen MCP-Client) über Streamable HTTP bereit, sodass Sie Fragen stellen können wie "finde die Fotos vom Kigali-Besuch im März" und echte Antworten von Ihrem eigenen NAS erhalten.

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

Warum es so gebaut ist

ChatGPT-Custom-Connectors akzeptieren nur einen entfernten HTTPS-Endpunkt. Es gibt keine stdio- oder localhost-Option, daher muss der Server vom Internet aus erreichbar sein — daher der Tunnel — und er muss sich selbst verteidigen, daher das Bearer-Token.

Werkzeuge

search und fetch sind bewusst so benannt: ChatGPTs Deep Research-Modus ignoriert alle anderen Werkzeuge, daher tragen diese beiden die Last, wenn der Entwicklermodus nicht verfügbar ist.

Einrichtung

1. Immich-API-Schlüssel abrufen

Immich → Kontoeinstellungen → API-Schlüssel → Neuer API-Schlüssel. Beschränken Sie ihn auf schreibgeschützt, es sei denn, Sie planen, Freigabelinks zu aktivieren.

2. Konfigurieren

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

Finden Sie das Docker-Netzwerk, auf dem Immich bereits läuft, und setzen Sie seinen Namen in docker-compose.yml unter networks.immich-net.name ein:

docker network ls | grep -i immich

Normalerweise ist es immich_default. Wenn der MCP-Container nicht beitreten kann, setzen Sie IMMICH_URL stattdessen auf die LAN-Adresse des NAS (http://192.168.1.50:2283) und entfernen Sie den networks:-Block.

3. Erstellen und ausführen

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

Lokal überprüfen, bevor Sie etwas freigeben:

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>

Der Smoke-Test führt den exakten Handshake durch, den ChatGPT macht — initialize, tools/list, dann einen Live-Tool-Aufruf — und bestätigt, dass nicht authentifizierte Anfragen einen 401 erhalten.

4. Über Cloudflare Tunnel freigeben

Fügen Sie Ihrem bestehenden Tunnel einen öffentlichen Hostnamen hinzu, der auf http://immich_mcp:8080 zeigt. Siehe cloudflared/config.example.yml. Wenn Sie den Tunnel über das Zero Trust-Dashboard verwalten, fügen Sie ihn stattdessen dort hinzu.

Stellen Sie Cloudflare Access nicht vor diesen Hostnamen. ChatGPT kann keinen interaktiven Access-Login abschließen.

Führen Sie den Smoke-Test erneut gegen die öffentliche URL aus:

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

5. ChatGPT verbinden

Einstellungen → Connectors → Erweiterte Einstellungen → Entwicklermodus aktivieren (erfordert einen kostenpflichtigen Plan), dann Erstellen:

• Name: Immich Photos

• Beschreibung: Das ist wichtig — das Modell liest sie, um zu entscheiden, ob der Connector aufgerufen werden soll. Etwa wie "Persönliche Foto- und Videobibliothek. Verwenden Sie sie zum Finden, Beschreiben oder Auflisten von Fotos, Alben und erkannten Personen."

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

• Authentifizierung: API-Schlüssel / benutzerdefinierter Header → Authorization: Bearer <token>

Aktivieren Sie dann den Connector im Chat-Composer.

Hinweise aus der Praxis

Nennen Sie das Werkzeug in Ihrer Eingabeaufforderung. ChatGPT wird nicht zuverlässig erraten, wann es einen benutzerdefinierten Connector verwenden soll. „Verwende immich search, um Fotos von den Trockengestellen zu finden“ funktioniert, während „finde meine Trockengestell-Fotos“ oft nicht funktioniert.

ChatGPT kann Ihre Fotos nicht sehen. Tool-Ergebnisse sind Text — Beschreibungen und Metadaten, keine Pixel. create_share_link existiert, um diese Lücke zu schließen, aber ein Freigabelink ist für jeden, der die URL kennt, öffentlich, weshalb er standardmäßig deaktiviert ist. Aktivieren Sie ihn nur, wenn Sie damit einverstanden sind.

Fixieren Sie Ihre Immich-Version. Die API ändert sich zwischen den Versionen — /server/statistics war vor nicht allzu langer Zeit /server-info/statistics. Ihre eigene Instanz veröffentlicht die genaue Spezifikation unter https://photos.example.com/api/docs; überprüfen Sie dort, bevor Sie einen 404 debuggen.

Rotieren Sie das Bearer-Token, indem Sie .env bearbeiten und docker compose up -d --force-recreate ausführen und dann den Connector in ChatGPT aktualisieren.

Fehlerbehebung