Immich Photo Manager

immich-photo-manager

用于通过 Immich 智能管理照片的 MCP 服务：了解您的可自托管图库。

这是 Drolosoft 推出的非官方社区插件，与 Immich 或 FUTO 没有关联，也未获得其赞助或认可；“Immich”是其名称，此处仅用于说明该插件适用的服务。插件通过 Immich 的公开 API 与您的 Immich 服务通信。

如果您的 Immich 图库规模已大到难以手动管理，immich-photo-manager 可让任何 AI 助手直接访问您的实例：通过自然对话搜索、整理、去重并策划相册。兼容 Claude、Gemma 或任何支持 MCP 的客户端。在本地运行，且仅与您的 Immich 通信；原始文件仍保留在您的服务上（请参阅哪些内容会离开您的网络）。

经过测试，而非想当然。 每次推送都会在 CI 上运行 364 项单元测试。每个版本发布前，也会在真实的 Immich 2.7.5 和 3.1.0 上进行实时测试（Docker，通过 MCP 协议测试全部 94 个工具，每次写入后重新读取状态），然后才会打标签；每次推送都会通过不依赖 SDK 的线路测试固定两种协议时代（旧版握手和无状态 2026-07-28）（tests/test_raw_wire_eras.py）。测试套件位于 tests/live/，任何人都可以复现。 doc/demos/ 中的演示是实际会话记录，演示 11 按提示词逐步展示了这一完整流程，演示 12 则使用真实片段处理视频帧并制作 PDF 照片书。 演示 13 至 18 展示了 2.x 中新增的所有功能（图库发现、OCR 和人物搜索、回忆与堆栈、合作伙伴与下载、资源备注、Docker 镜像），均来自真实会话。详情请参阅：测试方式。

---

功能介绍

说一句**“为我所有的旅行创建相册”**，看它如何完成：

GPS 坐标、CLIP 视觉搜索和时间匹配结合在一次请求中，即可创建数十个精心策划的相册。无需脚本，也无需手动整理。

---

快速入门

前提条件

• 正在运行的 Immich 实例（自行托管，v1.90+）
• Immich API 密钥（如何创建）
• Python 3.10+ 和 pip（下载）

安装（Claude Code 插件）

git clone https://github.com/drolosoft/immich-photo-manager.git
cd immich-photo-manager
pip3 install -r src/requirements.txt      # the plugin runs on your system python3

claude plugin marketplace add ./
claude plugin install immich-photo-manager

安装过程会提示有两个选项尚未设置：服务 URL 和 API 密钥。在会话中，/plugin 会通过对话框提示你填写（密钥会保存到系统的安全存储中）；在 shell 中，你可以通过 --config immich_base_url=... --config immich_api_key=... 传入这两项，也可以都留空，然后通过下面的设置流程保存。

打开 Claude Code（如果它已经打开，请重启），并将它连接到你的 Immich。按引导操作：

/setup-immich-photo-manager

它会询问你的服务 URL 和 API 密钥，将它们与服务进行验证，保存设置，并显示你的图库数据：

也可以跳过引导，一句话完成（底层执行相同操作）：

Update my Immich credentials to http://immich.local:2283 with API key <your API key>

无论使用哪种方式，凭据都会保存下来，供之后的每个会话使用；如需更换服务或密钥，只需重复操作。随时可以通过以下命令确认：

What Immich version am I connected to?

安装就完成了。如果你要使用 Claude Desktop、Cowork 或其他 MCP 客户端，而不是 Claude Code？这属于不含技能的纯 MCP 服务：请参阅入门指南，B 路径。

更新插件

只需一行，无需重新安装：

cd immich-photo-manager && git pull      # the clone you installed from
claude plugin marketplace update drolosoft-marketplace
claude plugin update immich-photo-manager@drolosoft-marketplace

然后重启 Claude Code。drolosoft-marketplace 是从克隆仓库添加市场时使用的名称（运行 claude plugin marketplace list 可以查看）。已保存的凭据会保留。

拉取新版本后，请再次运行 pip3 install -r src/requirements.txt：1.7.1 将视频（av）和 PDF（fpdf2）库加入了插件依赖项。使用 uvx 方式时，先运行一次 uvx --refresh immich-photo-manager --help，然后重启客户端。

从 2.0.12 升级

无需重新设置。选项、服务命令和工具名称都与 2.0.12 相同，已保存的凭据也会保留。以下是变化之处：

• 建议在插件的配置对话框（/plugin，然后选择插件选项）中设置服务 URL 和 API 密钥，这样密钥会保存在系统的安全存储中。如果你通过 /setup-immich-photo-manager 进行连接，该方式仍然有效，无需迁移任何设置。
• 仓库中的图像已重新保存，不含颜色配置文件或 EXIF 数据。它们看起来没有变化。
• README 现在集中列出了插件运行、发送和获取的所有内容。

哪些内容会离开你的网络

插件进程在你的计算机上运行，并且只与 Immich 通信。但助手通过它读取的所有内容都会发送给你使用的模型：文件名、日期、EXIF、相册列表，以及当你让它查看图片时的缩略图（默认 250px，按需提供 1440px 预览）。不会获取原图。使用 Claude 时，这意味着这些缩略图会离开你的网络；使用通过 MCP 连接的本地模型（LM Studio、Ollama）时则不会。除非你主动要求，否则不会发送任何内容：列出相册或修正日期只会传输文本；“告诉我这些照片里有什么”则会传输图像。

PDF 报告也遵循相同规则：export_pdf 会在运行服务的计算机上将文件写入磁盘，除非你传入 return_base64=true，否则不会将文件发送到任何地方。文件会保存到 output_path 指定的位置（默认为桌面）；不会覆盖现有文件。仅放入 PDF 的帧不会离开你的计算机，也不会消耗令牌；只有你要求模型查看的帧才会发送。当资源包含 GPS 数据时，“地点”页面会使用来自 tile.openstreetmap.org 的地图切片绘制地图，这是服务本身唯一一次第三方调用；传入 map=false 可跳过此操作，将所有内容留在你的网络内。

插件运行、发送和获取的内容

• 运行：一个本地进程，即 MCP 服务，通过 python3 启动插件中的文件（src/plugin_entry.py）。没有钩子，也没有后台任务，启动时不会下载或安装任何内容。Python 库需要你自行从 src/requirements.txt 安装。
• 你的 Immich 服务：每个工具都会调用你配置的 Immich 服务公开 API，并在 x-api-key 请求头中携带你的 API 密钥。upload_asset 会将你指定的本地文件发送到该服务。
• 插件访问的其他服务：只有 tile.openstreetmap.org，且仅当 PDF 报告绘制 Places 地图时才会访问。请求会携带相应区域的地图瓦片坐标，因此会让该服务大致知道照片的拍摄地点。设置 map=false 可跳过此操作。
• 插件生成的页面访问的其他服务：图库页面不会从外部加载任何内容；手写字体嵌入在页面中。由你自己的机器提供服务的旅行地图会从 unpkg.com 加载 Leaflet 及其两个扩展，各自固定到一个版本，并带有 integrity 哈希值，因此浏览器会拒绝已更改的文件；地图瓦片则来自 OpenStreetMap，这会让这两个服务知道你查看的区域。缩略图会嵌入页面，或者在你设置 CORS 时从自己的 Immich 加载。
• 你机器上的文件：export_pdf 和 download_archive 会写入你指定的位置，绝不会覆盖文件。图库和地图是由助手写入的 HTML 文件。重复项报告可以读取磁盘上的导入文件夹来比较照片；只有在你批准确切的文件列表后，它才会移除其中的文件。
• 凭据：在插件的配置对话框中输入的 API 密钥会保存在系统的安全存储中。如果通过对话（/setup-immich-photo-manager 或 update_credentials）提供，密钥会像其他消息一样经过模型，并保存到只有你的用户可以读取的两个文件中：插件缓存文件夹里的 config.json 和 ~/.immich-photo-manager/config.json。
• 公开链接：create_shared_link 会创建任何拥有该 URL 的人都能打开的链接。只有在你要求分享时才会创建；list_shared_links 会显示现有链接，delete_shared_link 会将其删除。
• 删除：delete_assets 会将资源移入 Immich 的回收站，restore_assets 可以撤销此操作。只有设置 force=true 时才会彻底删除；empty_trash 也是永久操作。清理和重复项技能会显示发现的内容，并在删除任何内容前等待你的答复。插件绝不会更改 Claude 的权限设置。

连接、检查、切换：只需对话

完成设置后，你无需再编辑配置文件。连接通过对话管理：

你说	会发生什么
“我连接的 Immich 版本是什么？”	报告服务版本和正在连接的 URL
“将我的 Immich 凭据更新为 https://photos.example.com，API 密钥为 ...”	验证该密钥对该服务是否有效，热切换当前连接并保存，无需重启
“显示我的 Immich 连接”	显示 URL 和已遮蔽的 API 密钥

一次只能连接一个服务：要使用第二个 Immich（测试实例或朋友的服务），再次说出 更新 这句话；要切换回来，再说一次即可。URL 或密钥有误？它会告知你，并保留之前的连接。

试试完整演示：演示 11：相册逐步讲解。逐项阅读相册，查找重复出现的人物，创建子相册，并为每张照片添加标签和描述。

支持 Claude Code

同一插件也可在 Claude Code 中运行：直接在终端搜索你的图库、整理相册并生成图库页面。

完整对话记录：Claude Code 演示

兼容任何 MCP 客户端

immich-photo-manager 是一款 MCP 服务：它适用于任何使用 Model Context Protocol 的 AI 助手，而不仅仅是 Claude。

直接使用 uvx 启动包入口点：

{
  "mcpServers": {
    "immich": {
      "command": "uvx",
      "args": ["immich-photo-manager"],
      "env": {
        "IMMICH_BASE_URL": "https://your-immich-server.com",
        "IMMICH_API_KEY": "your-api-key"
      }
    }
  }
}

immich-photo-manager 默认使用 MCP stdio 传输。要将服务作为 Streamable HTTP 服务运行，请设置 MCP_TRANSPORT=http。

🐳 作为 Docker 容器运行

此服务也以多架构镜像（amd64 + arm64）的形式发布在 GitHub Container Registry 上，通过 HTTP 在端口 8626 提供 MCP 服务，兼容两个协议版本，提供相同的 94 个工具：

docker run -d -p 8626:8626 \
  -e IMMICH_BASE_URL=https://your-immich-server.com \
  -e IMMICH_API_KEY=your-api-key \
  -v ./exports:/data \
  ghcr.io/drolosoft/immich-photo-manager

将任何 Streamable HTTP 客户端指向 http://localhost:8626/mcp。存活状态接口位于 /health（无需凭据，并已配置为镜像的 HEALTHCHECK）。会写入文件的工具（export_pdf、download_archive）会将文件存放在 /data，因此请在此处挂载卷。如果通过 localhost 以外的名称（例如反向代理或另一个容器）访问容器，需要将该名称添加到 -e MCP_ALLOWED_HOSTS=...。DNS 重绑定保护保持启用。

环境变量为可选项：不设置它们启动的容器仍可提供服务，每个工具都会返回“未配置 Immich 凭据”及解决方法；调用一次 update_credentials（提供 base_url + api_key）即可连接，凭据会保存在 /data 下。因此，挂载卷后，即使重启或重新创建容器，凭据也会保留。

也可以像这样将其作为 Compose 服务运行，与 Immich 集群并列部署或独立运行：

services:
  immich-mcp:
    image: ghcr.io/drolosoft/immich-photo-manager
    ports:
      - "8626:8626"
    environment:
      IMMICH_BASE_URL: https://your-immich-server.com
      IMMICH_API_KEY: your-api-key
      # MCP_ALLOWED_HOSTS: photos-mcp.example.com   # only behind a proxy / other hostname
    volumes:
      - ./exports:/data
    restart: unless-stopped

**macOS 上的 Claude Desktop：**该应用无法读取 shell 的 PATH，因此请在 "command" 中填写 uvx 的完整路径（在终端运行 which uvx；通常是 /Users/<you>/.local/bin/uvx 或 /opt/homebrew/bin/uvx）。先在终端运行一次 uvx immich-photo-manager --help，完成首次下载，然后按 Cmd+Q 退出 Claude Desktop 并重新打开。如果仍未显示，原因可在 ~/Library/Logs/Claude/mcp-server-immich.log 中查看。

============================================================
IMMICH-PHOTO-MANAGER × GEMMA 4 (LM STUDIO)
============================================================

Immich: https://your-immich-server.com
Model:  gemma4-26b-it (local, LM Studio)
Query:  "Show me my Lanzarote albums"

1. Getting MCP tool schemas...
   94 MCP tools available

2. Asking Gemma 4...
   Gemma 4 chose: list_albums({})

3. Executing 'list_albums' against Immich...
   Found 124 total albums, 14 Lanzarote albums:
     - Lanzarote Amarillo (26 photos)
     - Lanzarote Rojo (201 photos)
     - Lanzarote Azul (187 photos)
     - Lanzarote Marrón (208 photos)
     - Lanzarote Negro (193 photos)
     - Lanzarote Verde (201 photos)
     - Lanzarote Gasolina (174 photos)
     ...

4. Gemma 4 interpreting results...
   "I found 14 Lanzarote albums, 7 color-themed with
    1,190 photos and 7 location-specific albums."

RESULT: Zero cloud dependency, fully self-hosted stack.

客户端	状态
Claude Code	已测试
Claude Desktop	已测试
LM Studio (Gemma 4)	已测试
Cursor、Windsurf、VS Code、Cline、Zed	兼容（MCP stdio）

完整对话记录：Gemma 4 演示 · 测试脚本：test-lmstudio-mcp.py

---

亮点

• AI 驱动的搜索：通过 CLIP 使用自然语言搜索照片（“海滩上的日落”“生日蛋糕”）
• 地理相册：按地点创建相册，结合 GPS、CLIP 和时间匹配
• 元数据修复：修正正午/午夜时间戳，从相邻照片推断缺失的 GPS 信息，校正时区偏移
• 资料库清理：通过多信号分析检测截图、重复项和低质量图片；近似重复项和连拍照片可以堆叠在最佳照片下方，而不是删除，且可撤销
• 重复项检测：使用感知哈希进行跨来源分析（查找 Apple Photos、Google Photos 和其他导入来源中的重新编码副本）
• 批量旋转：一次旋转整个相册或所选照片（90°/180°/270°）；非破坏性操作，可累积多次调用的旋转角度，并支持一键还原
• PDF 报告：将相册或所选照片制作为包含元数据、视频帧和 Claude 说明文字的 PDF，全部在你的设备上完成；影集布局会为每个选定的视频片段单独生成一页并配上说明文字，封面、索引和地点页面均为可选
• 视频帧：从任意视频片段中均匀截取帧，或从指定片段（start/end）按每秒最多一帧的频率（interval）截取，让 Claude 描述其中发生的内容；Immich 本身只会为每个视频保留一张预览图
• 人物与面部管理：列出、搜索、合并和整理已识别的人物；重新分配识别错误的面部；查看面部缩略图
• 回收站与资产生命周期：安全地将资产移至回收站、永久删除，或从回收站恢复；完整管理资产生命周期
• 资料库健康状况：通过一条命令查看资产清单、元数据质量、存储空间明细和建议
• 标签与整理：在资料库中创建、应用和管理标签；批量添加或移除资产标签
• 了解服务端状态：一次调用即可报告 Immich 版本、已启用的功能（OCR、智能搜索、人脸、地图）以及该主版本的已知行为，不会提供服务端无法执行的操作
• 照片中的文字：OCR 可识别照片中的文字（票据、街道标志），探索、城市和建议调用会返回筛选器所需的准确拼写，而不是猜测
• 一次调用获取日期信息：按月汇总、显示空档和繁忙日期的日历热力图，以及 Immich 的“历史上的今天”回忆
• 双向共享：合作伙伴资料库（Immich 的家庭共享），以及他人在共享相册中留下的评论和点赞
• 导出原件：在你的设备上将整个相册或所选照片打包成一个 zip 文件，并在开始下载前报告文件大小
• 跨会话备注：为每个资产保存判断结果和操作记录，让下一次清理跳过之前已审核的内容
• 在 Docker 中运行：支持多架构的镜像通过 HTTP 在端口 8626 上提供 MCP 服务，兼容两个协议版本，共有 94 个工具
• 交互式图库：自包含的 HTML 页面，内嵌缩略图，提供 3 种主题、4 种查看模式和用于批量操作的 Cowork Actions Panel

在图库中选择照片，点击一项操作，然后将命令粘贴到 Claude 中。所有 13 项技能请参阅 技能参考。

---

工具

按类别列出的 94 个工具。每个工具的参数、返回结构和示例请参阅 MCP Tools Reference。

• 搜索：search_smart、search_metadata、search_explore、search_cities、search_places、search_suggestions、search_random、search_statistics、search_large_assets、list_assets
• 相册：list_albums、get_album、create_album、update_album、delete_album、add_assets_to_album、remove_assets_from_album
• 资源和元数据：get_asset_info、update_asset_metadata、update_assets_metadata、rotate_assets、revert_asset_edits、get_map_markers、reverse_geocode、upload_asset
• 图像和缩略图：get_asset_image、get_album_images、get_images_batch、get_asset_thumbnail、get_album_thumbnails、get_thumbnails_batch
• 视频和 PDF：get_video_frames、get_video_frames_json、get_export_preview、export_pdf
• 人物和人脸：list_people、get_person、update_person、merge_people、search_people、get_person_thumbnail、get_asset_faces、reassign_face
• 重复项和堆栈：get_duplicates、resolve_duplicates、create_stack、list_stacks、get_stack、update_stack、delete_stack
• 标签：list_tags、get_tag、create_tag、update_tag、delete_tag、tag_assets、untag_assets
• 日期：get_timeline_buckets、get_timeline_bucket、get_calendar_heatmap、list_memories、create_memory、update_memory、delete_memory
• 共享：list_shared_links、create_shared_link、get_shared_link、update_shared_link、delete_shared_link、list_users、list_partners、create_partner、update_partner、remove_partner、list_activities、create_activity、delete_activity
• 下载：get_download_info、download_archive
• 回收站：delete_assets、empty_trash、restore_trash、restore_assets
• 资源备注：review_assets、record_action、get_asset_notes、get_assets_notes、clear_asset_notes
• 服务和连接：ping、get_server_version、get_capabilities、get_statistics、get_connection_info、update_credentials

---

为什么选择 immich-photo-manager？

Immich 非常适合存储和查看照片。但要管理大型照片库（去重、修复元数据、整理相册、分析存储），仍需手动操作或编写自定义脚本。

	手动操作 / 脚本	immich-photo-manager
🔍	编写 API 调用、解析 JSON	自然语言：“查找我在意大利拍的日落照片”
🗺️	导出 GPS 数据，手动聚类	地理相册：自动结合 GPS、CLIP 和时间进行匹配
🧹	对文件进行哈希处理、比对校验和	感知哈希：查找来自不同导入源的重新编码重复项
🔧	一次编辑一个文件的 EXIF	元数据修复：批量修正时间戳、推断 GPS、校正时区
📊	查询数据库、生成报告	照片库健康状况：用一条命令检查元数据质量、存储情况并获取建议
🔄	一次旋转一张照片	批量旋转：一次旋转整个相册，且不会破坏原图
🏷️	UI 中没有标签管理功能	标签：创建标签，并对多个资源进行批量添加或移除
📅	滚动时间轴寻找缺失内容	时间轴地图：一次调用即可查看按月分组的数据和日历热力图，包括缺失时段
🔤	搜索文件名，全凭运气	OCR 搜索：按照片中的文字查找照片
📦	SSH 登录并手动压缩文件	下载归档：将相册原图打包为一个 ZIP，并提前获知大小
🧠	每次会话都要重新判断相同的照片	资源备注：判断结果保留在资源上，下次处理时会跳过它
🛡️	手动审核每项操作	安全优先：先显示发现结果，执行前征求确认

---

测试方式

• 每次推送运行单元测试套件：在 Python 3.10 和 3.13 上运行 364 个 pytest 用例（使用模拟 HTTP），并运行 ruff。只有通过这道门槛才会发布版本。
• 每个工具均进行实测，覆盖两个 Immich 版本：tests/live/ 会在 Docker 中启动真实的 Immich 2.7.5 和 3.1.0，为它们填充一个小型图库，并通过 MCP 协议调用全部 94 个工具，每次写入后都会重新读取状态。每次发布前运行；最近一次完整运行于 2026-09-03，两者均通过 132/132 项检查。
• 实际使用情况：PyPI 下载量、来自四位外部贡献者且已合并的 PR，以及 doc/demos/ 中的演示，都是实际会话的记录。

使用 Claude 构建

这是一个 Claude 插件，Claude 也参与了代码编写：设计、API 兼容性决策以及测试内容由作者负责；相当一部分实现和测试框架由 Claude Code 编写。无论变更由谁编写，都会经过相同的检查流程：在 CI 上运行测试；任何涉及 Immich API 的变更还会运行上述实测。

文档

文档	说明
入门指南	安装、手动配置 MCP、部署选项和故障排查
环境配置	详细配置：git、Python、venv、HTTP/stdio 启动、Open WebUI 和常见问题
Skills 参考	全部 13 个 skill：工作流、触发条件、参数和输出格式
MCP 工具参考	全部 94 个 MCP 工具：参数、返回类型和示例
架构	如何通过嵌入 base64 缩略图解决 Cowork 沙盒限制
MCP 2026-07-28	双时代支持：同一 MCP 服务中的旧版握手和无状态修订版，以及验证方式
CORS 配置指南	可选配置：启用直接 URL 缩略图加载，以供在浏览器中查看图库

---

🦙 Glama 评分

---

贡献

欢迎贡献：修复错误、新增技能、提出功能创意。请提交 issue 或 PR。

如果 immich-photo-manager 帮助你管理图库，欢迎在 GitHub 上点亮星标，帮助其他人发现这个项目。

---

支持

如果 immich-photo-manager 为你节省了时间，或让图库管理变得更轻松，欢迎请我喝杯咖啡。你的支持将助力我继续开发！

---

许可证

MIT 许可证：可免费使用、修改和分发。

由 Drolosoft 打造 · 我们希望存在的工具