内容
<h1 align="center">immich-mcp</h1>
<p align="center"><strong>一款将自托管Immich照片和视频库置于LLM工具调用之后的MCP服务器，以便AI客户端可以通过普通语言搜索、策划和清理。</strong></p>
<p align="center">
<a href="https://www.npmjs.com/package/immich-mcp"><img src="https://img.shields.io/npm/v/immich-mcp?style=for-the-badge&label=npm&color=2563EB" alt="npm版本" /></a>
<a href="https://github.com/lidless-labs/immich-mcp/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/lidless-labs/immich-mcp/ci.yml?branch=master&style=for-the-badge&label=ci" alt="CI状态" /></a>
<img src="https://img.shields.io/badge/Node.js-20%2B-339933?style=for-the-badge&logo=node.js&logoColor=white" alt="Node.js 20+" />
<img src="https://img.shields.io/badge/MCP-1.x-7C3AED?style=for-the-badge" alt="MCP 1.x" />
<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-2EA043?style=for-the-badge" alt="MIT许可证" /></a>
</p>
<p align="center">
<a href="https://lidless.dev/immich-mcp"><strong>官网</strong></a>
·
<a href="https://www.npmjs.com/package/immich-mcp">npm</a>
·
<a href="https://immich.app">Immich</a>
</p>
**它是什么。** `immich-mcp`是一个适用于Immich的[模型上下文协议](https://modelcontextprotocol.io)服务器，Immich是一个自托管的照片和视频库。它将Immich API暴露为类型化的MCP工具，因此任何MCP客户端，如Claude Desktop、Claude Code、OpenClaw或Codex CLI，都可以直接驱动您的照片和视频库：
- **搜索**您的照片库通过自然语言（CLIP / 智能搜索），通过元数据（日期，位置，相机，人，标签），或通过服务器端发现提要。
- **策划**相册，标签，共享链接和堆栈（运动照片，括号拍摄，RAW + JPEG对）。
- **识别人**: 列出识别的面部，重新命名它们，合并重复的面部集群，为未命名的集群建议名称。
- **显示记忆**: “在这一天”车道，当天的摘要和最近上传的摘要，适合每日cron投递。
- **清理重复文件和回收站**: 分类重复组，找到字节相同的或CLIP分组的重复文件，审计活动库和回收站的可回收空间，并通过可配置的保留策略解决。
**为什么使用它。** Immich已经在您的照片中保存了整个生活，但是网页UI是为点击而构建的，而不是为询问而构建的。通过MCP连接它，让您可以说“找到去年夏天所有的日落照片并将它们放入一个相册”或“显示占用回收站最多空间的内容”，并让代理通过审核的工具调用完成工作，而不是手动点击。
**它与众不同。** 它是可用的最广泛的Immich MCP表面：16个域中的74种工具，包括其他Immich MCP服务器不涵盖的记忆，重复检测与校验和安全解决，回收站审计和运动照片堆栈。默认情况下写入是关闭的，破坏性调用需要明确的确认，因此代理无法悄悄删除您的照片。
## 它做什么
`immich-mcp`通过模型上下文协议将自托管的Immich照片库连接到LLM。它将Immich的REST API转换为74个类型化、模式验证的工具调用，分为16个域，因此兼容MCP的AI客户端可以直接驱动您的照片和视频库：
- **搜索**您的照片库通过自然语言（CLIP / 智能搜索），通过元数据（日期，位置，相机，人，标签），或通过服务器端发现提要。
- **策划**相册，标签，共享链接和堆栈（运动照片，括号拍摄，RAW + JPEG对）。
- **识别人**: 列出识别的面部，重新命名它们，合并重复的面部集群，为未命名的集群建议名称。
- **显示记忆**: “在这一天”车道，当天的摘要和最近上传的摘要，适合每日cron投递。
- **清理重复文件和回收站**: 分类重复组，找到字节相同的或CLIP分组的重复文件，审计活动库和回收站的可回收空间，并通过可配置的保留策略解决。
## 快速开始
```bash
# 1. 获取Immich API密钥：在Immich网页UI的帐户设置 > API密钥 > 新API密钥中。
# 2. 直接使用npx运行（无需安装）：
IMMICH_BASE_URL=https://photos.example.com/api \
IMMICH_API_KEY=your_key_here \
npx -y immich-mcp
```
服务器通过stdio进行MCP通信，因此它旨在由MCP客户端启动，而不是交互式使用。在下面的配置中将它连接到您的客户端。
## MCP客户端配置
将以下内容复制到您的MCP客户端配置文件中。它使用`npx -y immich-mcp`，因此无需全局安装任何内容：
```json
{
"mcpServers": {
"immich-mcp": {
"command": "npx",
"args": ["-y", "immich-mcp"],
"env": {
"IMMICH_BASE_URL": "https://photos.example.com/api",
"IMMICH_API_KEY": "YOUR_KEY",
"IMMICH_ALLOW_WRITES": "false"
}
}
}
}
```
- **Claude Desktop**：将上面的块添加到`~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或`%APPDATA%\Claude\claude_desktop_config.json`（Windows），然后重启Claude。
- **Claude Code**：
```bash
claude mcp add immich-mcp \
-e IMMICH_BASE_URL=https://photos.example.com/api \
-e IMMICH_API_KEY=YOUR_KEY \
-e IMMICH_ALLOW_WRITES=false \
-- npx -y immich-mcp
```
添加`--scope user`使其在任何目录都可用。
- **OpenClaw**：在`~/.openclaw/openclaw.json`的`mcps.entries.immich-mcp`下添加相同的`command` / `args` / `env`，然后`systemctl --user restart openclaw-gateway`和`openclaw mcp list`确认。
- **Codex CLI**：在`~/.codex/config.toml`中添加一个`[mcp_servers.immich-mcp]`块：
```toml
[mcp_servers.immich-mcp]
command = "npx"
args = ["-y", "immich-mcp"]
env = { IMMICH_BASE_URL = "https://photos.example.com/api", IMMICH_API_KEY = "YOUR_KEY", IMMICH_ALLOW_WRITES = "false" }
```
如果您更喜欢全局安装或源代码 checkout，请参阅[安装](#install)。
## 配置
在MCP客户端配置文件中设置以下环境变量：
| 变量 | 必需 | 默认值 | 描述 |
|----------|----------|---------|-------------|
| `IMMICH_BASE_URL` | 是 | - | 您的Immich API的基本URL，例如`https://photos.example.com/api`（或`http://192.0.2.10:2283/api`用于LAN主机）。 |
| `IMMICH_API_KEY` | 是 | - | Immich网页UI中帐户设置 > API密钥下的API密钥。 |
| `IMMICH_ALLOW_WRITES` | 否 | `false` | 设置为`true`以公开写入和删除工具。读取始终有效。 |
| `IMMICH_VERIFY_SSL` | 否 | `true` | 设置为`false`以接受自签名证书。宽松的TLS检查仅限于Immich客户端；它**不**禁用整个过程的证书验证。 |
| `IMMICH_UPLOAD_BASE_DIR` | 否 | - | `immich_upload_asset_from_path`限制在其中的绝对目录。未设置时，基于路径的上传将被拒绝。文件必须在该目录内解析（在跟随符号链接后）。 |
### 获取API密钥
1. 登录Immich。
2. 帐户设置 > API密钥 > 新API密钥。
3. 命名它（例如`mcp`）并复制该值。
## 工具
74种工具，涵盖16个领域。标记为*（需要`confirm: true`）的工具是破坏性的，拒绝在没有明确确认标志的情况下运行；所有写入和删除工具还需要`IMMICH_ALLOW_WRITES=true`。
### 系统（5）
- `immich_ping` - 验证连接，返回服务器响应
- `immich_get_server_info` - 服务器配置（登录页面，OAuth，主题）
- `immich_get_server_statistics` - 照片，视频和用户数量以及每个用户的存储
- `immich_get_capabilities` - 已启用的功能（搜索，ML，OAuth）
- `immich_get_storage` - 已用存储，可用存储，总存储和模板
### 资产（11）
- `immich_list_assets` - 分页列表/搜索，过滤（收藏，存档，日期，类型，人，专辑，标签）
- `immich_get_asset` - 资产的完整元数据
- `immich_get_asset_exif` - 资产的EXIF / IPTC块
- `immich_get_asset_statistics` - 每个用户的图像和视频数量
- `immich_download_asset_original` - Immich原始文件的URL路径
- `immich_download_asset_thumbnail` - Immich缩略图的URL路径
- `immich_upload_asset_from_path` - 上传本地文件（限制在`IMMICH_UPLOAD_BASE_DIR`内；未设置时拒绝）
- `immich_update_asset` - 描述，收藏，存档，评分，日期，地标
- `immich_bulk_update_assets` - 批量收藏/存档/可见性*（需要`confirm: true`）
- `immich_delete_asset` - 默认软删除（回收站）；`permanent: true`绕过回收站*（永久需要`confirm: true`）
- `immich_restore_from_trash` - 恢复以前已删除的资产
### 搜索（3）
- `immich_search_smart` - 通过自然语言查询的CLIP / 语义搜索
- `immich_search_metadata` - 结构化搜索（日期，位置，相机，人，标签，相册）
- `immich_search_explore` - 随机样本用于发现/“探索”车道
### 专辑（8）
- `immich_list_albums`
- `immich_get_album`
- `immich_get_album_statistics`
- `immich_create_album`
- `immich_update_album` - 重命名，设置封面，设置描述
- `immich_add_assets_to_album`
- `immich_remove_assets_from_album`
- `immich_delete_album` - 资产不会被删除*（需要`confirm: true`）
### 专辑流程（1）
- `immich_search_then_album` - 运行智能或元数据搜索，然后从匹配结果中创建一个相册*（写入受限）
### 人物（7）
- `immich_list_people`
- `immich_get_person`
- `immich_get_person_assets` - 人物出现的照片和视频
- `immich_update_person` - 名称，出生日期，可见性，收藏，特色脸
- `immich_hide_person` - 从默认列表中排除而不删除
- `immich_merge_people` - 将重复的面部集群合并为一个*（需要`confirm: true`）
- `immich_suggest_face_names` - 按面部计数列出未命名的人物，用于分类
### 标签（7）
- `immich_list_tags`
- `immich_get_tag`
- `immich_create_tag`
- `immich_update_tag` - 重命名或重新着色
- `immich_delete_tag` *（需要`confirm: true`）
- `immich_add_tag_to_assets`
- `immich_remove_tag_from_assets`
### 共享链接（5）
- `immich_list_shared_links`
- `immich_get_shared_link`
- `immich_create_shared_link`
- `immich_update_shared_link`
- `immich_delete_shared_link` *（需要`confirm: true`）
### 活动（4）
- `immich_list_activities` - 相册或资产上的评论和点赞
- `immich_get_activity_statistics`
- `immich_create_activity`
- `immich_delete_activity` *（需要`confirm: true`）
### 记忆（2）
- `immich_list_memories` - 记忆车道（“years ago”等）
- `immich_get_memory`
### 记忆流程（2）
- `immich_memories_today` - 今日的“X年前”车道，聊天格式
- `immich_daily_digest` - 服务器统计数据 + 今日记忆 + 最近上传的markdown文件
### 重复文件（2）
- `immich_list_duplicates` - Immich的哈希遍历检测到的重复文件组
- `immich_resolve_duplicates` - keep[] / discard[]，默认为dry-run *（`delete: true` + `confirm: true`删除）
### 重复文件流程（8）
- `immich_categorize_duplicates` - 归类重复组（校验和精确，名称-大小，分辨率变体，突发，编辑）
- `immich_find_byte_dupes` - 准备删除的候选文件，具有`safetyMode`（默认严格校验和）
- `immich_resolve_with_keep_strategy` - 终极重复删除，默认为dry-run，适用于相册
- `immich_explain_duplicate_group` - 每个资产的详细资料和推荐的保管人，并提供理由
- `immich_find_clip_dupes` - 视觉但非字节相同的CLIP分组对（只读）
- `immich_compare_assets` - 2-10个资产的并排元数据差异对比，并提供建议
- `immich_audit_active` - 活动库中可回收的重复候选文件
- `immich_audit_trash` - 交叉检查已删除的资产与活动库中的孤儿
### 堆栈（4）
- `immich_list_stacks` - 堆栈组（运动照片，括号拍摄，RAW + JPEG对）
- `immich_create_stack`
- `immich_update_stack` - 重新分配主要资产
- `immich_delete_stack` - 资产保留*（需要`confirm: true`）
### 回收站（3）
- `immich_list_trash` - 分页回收站资产，范围限定为回收站
- `immich_restore_by_query` - 恢复回收站中匹配过滤器的资产*（无过滤器需要`confirm: true`）
- `immich_empty_trash` - 永久删除回收站中的所有内容，不可逆*（需要`confirm: true`）
### 作业（2）
- `immich_list_jobs` - 作业队列状态（缩略图，ML，元数据，边车）
- `immich_run_job` - 向后台作业发送命令*（破坏性命令需要`confirm: true`）
## 示例提示
> 显示本周的记忆。
调用`immich_memories_today` / `immich_list_memories`并过滤当前周。
> 查找重复照片并告诉我哪些删除（暂不删除）。
调用`immich_categorize_duplicates` / `immich_list_duplicates`并返回集群作为dry run，无需解决任何问题。
> 将这些运动照片分组到一个堆栈中。
调用`immich_create_stack`与资产ID和主要选择。
> 创建一个去年八月的海滩照片相册。
调用`immich_search_then_album`搜索并创建相册，写入受限。
## 安全模型
`immich-mcp`设计为安全地交给自主代理：
- **读取始终允许。写入是可选的。** 写入和删除工具仅在`IMMICH_ALLOW_WRITES=true`时注册。
- **破坏性调用需要明确的`confirm: true`。** 大批量更新，永久删除，合并，清空回收站等操作拒绝运行，否则即使启用写入也是如此。
- **重复文件默认为dry-run。** 分辨率工具在触摸任何内容之前报告它们将执行的操作。
- **基于路径的上传是限定的。** `immich_upload_asset_from_path`仅读取`IMMICH_UPLOAD_BASE_DIR`（在跟随符号链接后），并且在未设置时完全拒绝。
- **宽松的TLS是作用域的。** `IMMICH_VERIFY_SSL=false`仅放松Immich客户端的分派器；它不削弱证书验证过程的范围。
## 安装
上面的快速启动使用`npx -y immich-mcp`，无需安装。要全局安装：
```bash
npm install -g immich-mcp`
```
或从源代码：
```bash
git clone https://github.com/lidless-labs/immich-mcp.git
cd immich-mcp
npm install
npm run build`
```
从源代码checkout运行时，请将客户端的`command`指向`node`，并将`args`指向`dist/index.js的`绝对路径。
## 为什么不选择其他选项？
- **Immich网页UI**是为通过网格点击而构建的。它适用于浏览，但不适合“对数千张照片执行X”。该服务器是批量查询驱动的代理辅助工作，UI不使其容易。
- **Immich CLI**上传和管理资产脚本，但它不是MCP服务器，并且LLM无法调用它作为类型化工具。`immich-mcp`是工具调用的表面。
- **其他Immich MCP服务器**倾向于涵盖基础知识（浏览，搜索，相册）。此服务器更广泛：74个工具涵盖记忆，运动照片堆栈，基于校验和的安全重复文件解析，回收站审计和作业控制，并内置两级写保护。
### immich-mcp 不是什么
- **它不是** Immich 的替代品。您仍然运行自己的 Immich 服务器；它将 AI 客户端连接到它。
- **它不是**托管服务。它在您的stdio上本地运行，由您的MCP客户端启动。除了指向的Immich服务器外，任何内容都不会被发送到任何地方。
- **它不是**照片编辑器或ML模型。它调用Immich现有的搜索，识别和重复检测功能；它不运行自己的功能。
- **它不**删除或修改任何内容，除非您设置`IMMICH_ALLOW_WRITES=true`，并且破坏性工具仍然需要每个调用`confirm: true`。
- **它不是**官方Immich项目。它是一个社区MCP服务器，使用公共Immich API。
## 许可
MIT - 参见 [LICENSE](LICENSE)。
