跳过安装。2 分钟内即可运行。
在 cloud.anythingmcp.com 开始免费试用，一键添加 Immich，然后将你的 AI 客户端（Claude、ChatGPT、Copilot 或 Cursor）指向生成的 MCP 端点。无需 Docker，无需 git clone，无需任何工程经验。
AnythingMCP 已收录在 Claude 的连接器目录中：一键添加到 Claude (在新标签页中打开)，然后登录并选择 Claude 可以使用哪些 MCP 服务器。
摘要
让你的 AI 读取你的 Immich 照片库:照片和视频的数量、相册及其共享对象、照片的日期、地点、相机和人物、Immich 识别出的人物,以及每个月拍摄的照片数量。只读:绝不会上传、编辑或删除任何内容。适用于自托管的 Immich 3.0 或更高版本。
试试这样问
Immich 的示例提示
点击任意提示即可复制，然后粘贴到 Claude、ChatGPT、Cursor、Gemini、Copilot 或 OpenClaw 中，在该连接器上运行。
Claude 是 AI，可能会出错。请核对回答。
💡 不想安装?直接使用 cloud.anythingmcp.com。 登录后,点击 Connectors → Immich,粘贴你的凭据,生成一个 MCP API 密钥即可完成。无需 Docker,无需
git clone,无需本地服务器。
Immich + Claude
让你的 AI 读取你的 Immich 照片库:照片和视频的数量、相册及其共享对象、照片的日期、地点、相机和人物、Immich 识别出的人物,以及每个月拍摄的照片数量。只读:绝不会上传、编辑或删除任何内容。适用于自托管的 Immich 3.0 或更高版本。
前提条件
请查看连接器内置的完整设置说明(在应用内商店选择该连接器即可看到)。此连接器所需的环境变量如下:
IMMICH_URL, IMMICH_API_KEY
第 1 步 — 获取凭据
设置大约需要 3 分钟。你需要 Immich 3.0 或更高版本,以及一个来自用户的 API 密钥,AI 将读取该用户的照片库。无需管理员账号。
- 将
IMMICH_URL设置为你访问 Immich 时使用的地址,不要带/api,也不要带末尾斜杠,例如https://photos.example.com或http://192.168.1.10:2283(默认端口为 2283)。 - 以该用户身份登录 Immich,打开 Account Settings → API Keys → New API Key,只授予
user.read、asset.read、asset.statistics、album.read和person.read权限。将密钥复制到IMMICH_API_KEY;Immich 只会显示一次。它通过x-api-key请求头发送。 - 安装连接器并运行
immich_get_my_user:它会显示该密钥对应的用户,以及其存储配额和已用空间。
Immich 的运行位置:在自托管的 AnythingMCP 上,Immich 通常运行在家用服务器或 NAS 上(http://192.168.x.x:2283)。出站 SSRF 防护默认会阻止私有和本地地址,因此管理员必须通过 SSRF_ALLOWED_HOSTS 或管理设置中的允许列表放行该主机。AnythingMCP Cloud 只能访问通过 HTTPS 暴露在公网上的 Immich 服务器,例如部署在反向代理之后。私有 IP 或本地主机名会被拒绝,并且在 Cloud 上无法修改允许列表。
可读取的内容:使用 immich_get_asset_statistics 获取照片和视频数量(不带过滤条件时,它会统计回收站之外的所有资产,包括已归档的;visibility=timeline 与主时间线一致);相册及其共享对象(immich_list_albums、immich_get_album);单张照片或视频的日期、相机、镜头、曝光、GPS、城市、国家、人物和标签(immich_get_asset);按名称查找已识别的人物(immich_search_people);按名称查找地点及其坐标(immich_search_places);以及按人物、相册、标签或收藏统计每月数量(immich_get_timeline_buckets)。所有 id 均为 UUID。
隐私:Immich 密钥只能看到创建它的用户的照片库,以及与该用户共享的相册,也就是其中的照片、人脸和位置信息。请仅将此连接器分配给其用户有权查看该照片库的 MCP 服务器。服务器文件路径、校验和、thumbhash、OAuth id 和许可证密钥会从返回结果中移除。
常见错误:401 表示密钥错误或已被删除;401 "Elevated permission is required" 表示涉及锁定文件夹,API 密钥无法读取。403 "Missing required permission" 表示密钥缺少这五项权限之一。400 "Not found or no ... access" 表示此照片库中不存在该 id 对应的资产或相册(Immich 返回的是 400,而不是 404)。400 "Validation failed" 表示 id 不是 UUID、某个值不被允许,或者人物或地点搜索缺少 name。每次调用都返回 404 表示 IMMICH_URL 有误,或以 /api 结尾。
该连接器是只读的:它不会上传、编辑、收藏、归档、移入回收站或删除资产,不会更改相册、标签或人物,不会下载原始文件、缩略图或视频,不会运行智能搜索或元数据搜索,也不会访问锁定文件夹、共享链接、回忆、管理员端点或 API 密钥管理。
第 2 步 — 安装适配器
curl -fsSL https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml -o docker-compose.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d
第 3 步 — 在 Claude 中添加连接器
你的服务器 URL: 在 AnythingMCP 中,打开 MCP Servers → 此连接器所在的服务器,复制其 URL(
https://cloud.anythingmcp.com/mcp/…)。本指南中出现YOUR_SERVER_ID的地方都使用它。
推荐方式 — 在 claude.ai 网页版上无需编辑任何配置文件即可使用。
- 在 Claude 中,打开 Customize → Connectors。
- 点击 +,然后点击 Add custom connector。
- 输入名称,例如
Immich,以及远程 MCP 服务器 URLhttps://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID,然后点击 Add。 - 点击 Connect 并登录 AnythingMCP(OAuth)以授权访问。
下面所有工具都会出现在你的聊天中 — 开始输入提示词即可。
可用工具
| 工具 | 功能 |
|---|---|
immich_get_my_user | 获取 API 密钥对应的 Immich 用户:id、名称、邮箱、是否为管理员,以及以字节为单位的存储配额和已用空间 |
immich_get_asset_statistics | 统计照片库中的照片和视频数量:{images, videos, total} |
immich_list_albums | 列出该用户拥有或与其共享的相册,精简为 id、名称、描述、资产数量、共享标记、日期范围… |
immich_get_album | 按 id 获取单个相册:名称、描述、资产数量、首张和末张照片的日期、缩略图资产 id、共享状态以及每位成员及其角色 |
immich_get_asset | 按 id 获取单张照片或视频:文件名、类型、拍摄和上传日期、收藏、归档和回收站状态、EXIF 数据(相机、镜头… |
immich_search_people | 按名称查找 Immich 通过人脸识别出的人物:id、名称、出生日期、收藏和隐藏标记 |
immich_get_timeline_buckets | 按月统计资产数量:每个有资产的月份对应一个 {timeBucket, count},按时间倒序排列,timeBucket 为该月的第一天… |
immich_search_places | 在 Immich 内置的地理编码数据中按名称查找地点:名称、地区(admin1name、admin2name)、纬度和经度,例如用于定位一张… |
常见问题
除了 Claude Desktop,它也适用于 Claude Code 吗? 是的 — 将两者都指向 https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID 即可。
后续步骤
这份指南对你有帮助吗?