Immich MCP サーバー

セルフホストの Immich フォトライブラリを ChatGPT（およびその他の MCP クライアント）に Streamable HTTP 経由で公開します。これにより、「3月のキガリサイト訪問の写真を見つけて」といった質問に対して、自分の 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 モードは他のすべてのツールを無視するため、Developer Mode が利用できない場合、これら 2 つが負荷を担います。

セットアップ

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 に接続する

設定 → コネクタ → 詳細設定 → Developer Mode を有効にする（有料プランが必要）、次に作成：

• 名前: 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 のコネクタ設定を更新します。

トラブルシューティング