Immich MCP 服务器

将自托管的 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 选项，因此服务器必须能从互联网访问—— 因此需要隧道——并且必须自我保护，因此需要 bearer 令牌。

工具

search 和 fetch 是特意命名的：ChatGPT 的深度研究模式会忽略 所有其他工具，因此如果开发者模式不可用，这两个工具将承担主要负载。

设置

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 局域网地址（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 之前先检查那里。

轮换 bearer 令牌，方法是编辑 .env 并运行 docker compose up -d --force-recreate，然后在 ChatGPT 中更新连接器。

故障排除