内容
<p align="center">
<img src="docs/assets/immichctl-banner.jpg" alt="immichctl banner" width="900">
</p>
<h1 align="center">immichctl</h1>
<p align="center"><strong>适用于 Immich 的操作员控制命令行工具，带有 MCP 适配器，允许 AI 客户端通过相同的安全工具界面搜索、策划和清理自托管的照片和视频库。</strong></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>
<p align="center">
<img src="https://img.shields.io/npm/v/immich-mcp?style=for-the-badge&logo=npm&label=npm" alt="npm version">
<img src="https://img.shields.io/github/actions/workflow/status/lidless-labs/immichctl/ci.yml?branch=master&style=for-the-badge&label=ci" alt="CI status">
<img src="https://img.shields.io/badge/MCP-compatible-8A2BE2?style=for-the-badge" alt="MCP compatible">
<img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="MIT License">
</p>
**这是什么。** `immichctl` 是适用于 [Immich](https://immich.app) 的操作员控制命令行工具，它是自托管的照片和视频库。 它为 shell、cron、CI 和自动化代理提供了一种类型化的方式来检查库、搜索资产、审计存储和运行常见的只读工作流。 同一个包通过 `immichctl mcp` 和后兼容的 `immich-mcp` 二进制文件为 MCP 客户端（如 Claude Desktop、Claude Code、OpenClaw 或 Codex CLI）提供了 Model Context Protocol（MCP）接口，允许它们浏览和搜索照片库、管理相册和标签、识别人物、显示记忆和解决重复项。
**为什么使用它。** Immich 已经在照片中记录了您的整个生活，但 Web UI 是为点击而设计的，不适合重复的操作工作流。 `immichctl` 提供了诸如 `immichctl server stats`、`immichctl search smart "sunset over the ocean"` 和 `immichctl duplicates` 等脚本命令；MCP 适配器允许 AI 客户端通过审计工具调用而不是手动点击来请求相同类型的工作。
**它与众不同之处。** 它是 ctl-first 和 MCP-compatible 的：该软件包安装了用于操作员的 `immichctl`，而 `immichctl mcp` 和 `immich-mcp` 保留了完整的 MCP 适配器。 MCP 接口仍然很广：74 种工具，涵盖 16 个领域，包括记忆、重复检测和带有校验和安全解析的重复项检测、垃圾审计和运动照片堆栈，这些是其他 Immich MCP 服务器不涵盖的。 默认情况下，写入是关闭的，破坏性调用需要明确确认，因此代理不能悄悄删除您的照片。
## 它能做什么
`immichctl` 将自托管的 Immich 照片库连接到操作员工作流和 MCP-compatible 的 AI 客户端。 命令行工具涵盖了只读的服务器、库、搜索、人员、相册、标签、重复项、作业和记忆工作流。 MCP 适配器将 Immich 的 REST API 转换为 74 种类型化、模式验证的工具调用，分为 16 个领域，因此 MCP-compatible 的 AI 客户端可以直接驱动您的照片和视频库：
- **搜索**您的照片库，通过自然语言（CLIP / 智能搜索）、元数据（日期、位置、相机、人物、标签）或服务器端发现提要。
- **策划**相册、标签、共享链接和堆栈（运动照片、连拍照片、RAW + JPEG 对）。
- **识别人物**：列出识别的面部，重新命名它们，合并重复的面部集群，为未命名的集群建议名称。
- **显示记忆**："在这一天"的车道、今日摘要和最近上传的摘要，适用于每日 cron 推送。
- **清理重复项和垃圾**：分类重复组，找到字节相同的或 CLIP 分组的重复项，审计活动库和垃圾以回收可用空间，并使用可配置的保留策略解决。
- **管理资产**：读取元数据和 EXIF，收藏、存档、评级、地理标签、软删除（垃圾）、恢复和从限定本地目录上传。
读取始终有效。写入和删除仅在您选择时出现，最具破坏性的操作需要每次调用 `confirm: true`。
## 安装
下面的 MCP 客户端配置使用 `npx -y immich-mcp`，无需全局安装即可使用，并保留现有的 npm 包名以保持兼容性。 要全局安装：
```bash
npm install -g immich-mcp
```
或者从源代码：
```bash
git clone https://github.com/lidless-labs/immichctl.git
cd immichctl
npm install
npm run build
```
当从源代码检出运行时，将客户端的 `command` 指向 `node`，将 `args` 指向 `dist/index.js` 的绝对路径。
## 快速入门
```bash
# 1. 获取 Immich API 密钥：在 Immich Web UI 中的帐户设置 > API 密钥 > 新的 API 密钥。
# 2. 运行 CLI 检查，无需全局安装：
IMMICH_BASE_URL=https://photos.example.com/api \
IMMICH_API_KEY=your_key_here \
npm exec --yes --package immich-mcp -- immichctl ping
```
全局安装后，操作员 CLI 可作为 `immichctl` 使用。要启动 MCP 适配器，请使用 `immichctl mcp` 或后兼容的 `immich-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" }
```
更喜欢全局安装或源代码检出？请参阅[安装](#install)。
## 工具
16 个领域中的 74 种工具。标有 *(需要 `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` - 记忆车道（年份等）
- `immich_get_memory`
### 记忆流程（2）
- `immich_memories_today` - 今日的“X年前”车道，聊天格式
- `immich_daily_digest` - 服务器统计数据 + 今日记忆 + 最近上传的markdown 降级
### 重复项（2）
- `immich_list_duplicates` - Immich 的哈希传递检测到的重复项组
- `immich_resolve_duplicates` - keep[] / discard[]，默认干运行 *(`delete: true` + `confirm: true` 删除)*
### 重复项流程（8）
- `immich_categorize_duplicates` - 归类重复项组（校验和精确、名称大小、分辨率变体、突发、编辑）
- `immich_find_byte_dupes` - 准备删除的候选者，具有 `safetyMode`（默认严格校验和）
- `immich_resolve_with_keep_strategy` - 端到端重复项删除，默认干运行，基于相册
- `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`)*
## 配置
在 shell 或 MCP 客户端配置文件中设置以下环境变量：
| 变量 | 必需 | 默认值 | 描述 |
|----------|----------|---------|-------------|
| `IMMICH_BASE_URL` | 是 | - | 您的 Immich API 基本 URL，例如 `https://photos.example.com/api`（或 `http://192.0.2.10:2283/api` 用于 LAN 主机）。 |
| `IMMICH_API_KEY` | 是 | - | Immich Web UI 中的 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`）并复制该值。
## 命令行工具
`immichctl` 是 shell、cron 和 CI 的主要操作员界面。它与 `@immich/sdk` 核心共享相同的 MCP 适配器，并读取相同的 `IMMICH_BASE_URL` / `IMMICH_API_KEY` 环境配置。它仅公开只读工具（服务器、库和搜索查找）；所有写入、删除、上传和作业控制工具都保留在 `IMMICH_ALLOW_WRITES` 门控下的 MCP 表面，并且无法从 CLI 访问。
```bash
npm exec --yes --package immich-mcp -- immichctl ping
# 或全局安装：
immichctl ping
immichctl server stats
immichctl storage
immichctl capabilities
immichctl albums list
immichctl albums get 00000000-0000-0000-0000-000000000001
immichctl assets list --type image --favorite --size 20
immichctl assets stats
immichctl people list --with-hidden
immichctl tags list
immichctl duplicates
immichctl jobs
immichctl memories --saved
immichctl search metadata --city Madrid --type image
immichctl search smart "sunset over the ocean"
immichctl server stats --json # 原始 JSON 用于管道传输
```
运行 `immichctl help` 以获取完整的命令和标志列表。 `--json` 发出原始 JSON 而不是简洁的人类可读摘要。退出代码：`0` 成功，`1` 运行时错误（Immich 不可达/调用失败），`2` 用法错误（未知命令/标志或错误值）。
将 `IMMICH_BASE_URL` 指向您的 Immich API，例如 `https://photos.example.com/api`（或 `http://192.0.2.10:2283/api` 用于 LAN 主机）。
### 启动 MCP 适配器
`immichctl mcp`（或后兼容的 `immich-mcp` 二进制文件）启动标准输入/输出 MCP 适配器。如果启动器直接引用文件路径 `dist/index.js`，则它仍然有效；新启动器可以指向 `dist/mcp-bin.js`（或 `dist/cli.js mcp`）。使用 `immich-mcp` 二进制文件名的启动器无需更改。
## 示例提示
> 显示本周的记忆。
调用 `immich_memories_today` / `immich_list_memories` 并按当前周筛选。
> 查找重复照片并告诉我哪些可以删除（暂不删除）。
调用 `immich_categorize_duplicates` / `immich_list_duplicates` 并返回群集，作为干运行返回，而不修改任何内容。
> 将这些运动照片分组到一个堆栈中。
调用 `immich_create_stack` 并带有资产 ID 和主要选择。
> 根据去年八月的海滩照片创建一个相册。
调用 `immich_search_then_album` 以搜索并在一个写入受控的步骤中创建相册。
## 安全模型
`immichctl` 和其 MCP 适配器设计为安全地交给自动化：
- **读取始终允许。写入是可选的。** 写入和删除工具仅在 `IMMICH_ALLOW_WRITES=true` 时注册。
- **破坏性调用需要明确的 `confirm: true`。** 批量更新、永久删除、合并、清空垃圾桶以及类似操作如果没有其他条件则拒绝运行。
- **重复项解析默认情况下为干运行。** 解决方案工具报告它们将执行的操作，然后再进行任何操作。
- **基于路径的上传仅限于目录。** `immich_upload_asset_from_path` 仅在 `IMMICH_UPLOAD_BASE_DIR` 之后解析（跟随符号链接），并且如果该变量未设置，则完全拒绝。
- **宽松的 TLS 仅限于 Immich 客户端。** `IMMICH_VERIFY_SSL=false` 仅宽松 Immich 客户端的 TLS 检查；它不会削弱整个进程的证书验证。
## 为什么不选择其他选项？
- **Immich Web UI** 设计用于浏览网格。 它非常适合浏览，手动操作不方便。
- **Immich CLI** 从脚本上传和管理资产，但它不是 MCP 适配器，LLM 无法调用它为类型化的工具。 `immichctl` 专注于操作员读取，而 `immichctl mcp` 和 `immich-mcp` 提供 MCP 工具调用表面，供代理使用。
- **其他 Immich MCP 服务器** 通常涵盖基础知识（浏览、搜索、相册）。 这个更广泛：74 种工具，涵盖记忆、运动照片堆栈、校验和安全解析、垃圾审计和作业控制，并内置两级写入保护模型。
- **自己编写围绕 Immich REST API 的粘合代码** 会起作用，但您需要重新实现模式验证、分页、写入门控、确认守卫和重复数据删除安全逻辑，而这些功能已经在该服务器中提供并经过测试。
## 这包是什么
- 它 **不是** Immich 的替代品。您仍然运行自己的 Immich 服务器；此服务器连接到 AI 客户端。
- 它 **不是** 一个托管服务。 CLI 在本地运行，MCP 适配器通过您的 MCP 客户端在标准输入/输出上运行。除了发送到您指向的 Immich 服务器外，任何内容都不会被发送到任何地方。
- 它 **不是** 照片编辑器或 ML 模型。它调用 Immich 现有的搜索、识别和重复项检测功能；它不运行自己的功能。
- 它不会 **删除或修改任何内容** 除非您设置 `IMMICH_ALLOW_WRITES=true`，并且破坏性工具仍然需要每次调用 `confirm: true`。
- 它 **不是** 官方 Immich 项目。它是一个社区操作员 CLI 和 MCP 适配器，使用公共 Immich API。
## 许可
MIT - 请参阅 [LICENSE](LICENSE)。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器