内容
<p align="center">
<img src="docs/assets/immichctrl-banner.jpg" alt="immichctrl banner" width="900">
</p>
<h1 align="center">immichctrl</h1>
<p align="center"><strong>适用于 Immich 的操作员控制 CLI，带有 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/immichctrl/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>
**它是做什么的。** `immichctrl` 是适用于 [Immich](https://immich.app) 的操作员控制 CLI，Immich 是自托管的照片和视频库。它为 shell、cron、CI 和自动化代理提供了一种输入方式来检查库、搜索资产、审计存储并运行常见的只读工作流。同一软件包通过 `immichctrl mcp` 和兼容的 `immich-mcp` 二进制文件为 MCP 客户端（如 Claude Desktop、Claude Code、OpenClaw 或 Codex CLI）提供了 Model Context Protocol（MCP）接口，以便它们可以浏览和搜索您的照片库、管理相册和标签、识别人物、显示记忆并以纯语言解决重复项。
**为什么使用它。** Immich 已经将您的整个生活存储在照片中，但 Web UI 是为点击设计的，而不是为可重复的操作工作流设计的。 `immichctrl` 为您提供了类似 `immichctrl server stats`、`immichctrl search smart "sunset over the ocean"` 和 `immichctrl duplicates` 的可脚本化命令；MCP 适配器允许 AI 客户端通过审计的工具调用请求相同类型的工作，而不是手动点击。
**它与众不同之处。** 它是 ctl-first 和 MCP-compatible 的：软件包安装了 `immichctrl` 用于操作员使用，而 `immichctrl mcp` 和 `immich-mcp` 保留了完整的 MCP 适配器可用。MCP 接口仍然很广：74 个工具，涵盖 16 个领域，包括记忆、重复检测（具有校验和安全解析）、垃圾审计和运动照片堆栈，这些是其他 Immich MCP 服务器不涵盖的。写入默认关闭，破坏性调用需要明确确认，因此代理无法悄悄删除您的照片。
## 功能
`immichctrl` 将自托管的 Immich 照片库连接到操作员工作流和 MCP-compatible AI 客户端。CLI 涵盖只读服务器、库、搜索、人员、相册、标签、重复项、作业和记忆工作流。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/immichctrl.git
cd immichctrl
npm install
npm run build
```
当从源代码 checkout 运行程序时，将客户端的 `command` 指向 `node`，并将 `args` 指向 `dist/index.js` 的绝对路径。
## 快速开始
```bash
# 1. 获取 Immich API 密钥：在 Immich 网页界面中，进入帐户设置 > API 密钥 > 新的 API 密钥。
# 2. 运行 CLI 检查，无需全局安装：
IMMICH_BASE_URL=https://photos.example.com/api \
IMMICH_API_KEY=your_key_here \
npm exec --yes --package immich-mcp -- immichctrl ping
```
全局安装后，操作员 CLI 可作为 `immichctrl` 使用。要启动 MCP 适配器，请使用 `immichctrl 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" }
```
优先使用全局安装或源代码 checkout？请参阅 [安装](#安装)。
## 工具
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` - 记忆车道（“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` - 准备好-trash 候选人，启用 `safetyMode`（默认严格校验和）
- `immich_resolve_with_keep_strategy` - 终极 deduplicate，默认为 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`)*
## 配置
在 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 网页界面中的 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`），复制该值。
## CLI
`immichctrl` 是 shell、cron 和 CI 的主要操作员界面。它与 MCP 适配器共享 `@immich/sdk` 核心，并读取相同的 `IMMICH_BASE_URL` / `IMMICH_API_KEY` 环境配置。它仅公开只读工具；所有写入、删除、上传和作业控制工具都保留在 MCP 接口中，位于 `IMMICH_ALLOW_WRITES` 门控后面，无法从 CLI 访问。
```bash
npm exec --yes --package immich-mcp -- immichctrl ping
# 或全局安装：
immichctrl ping
immichctrl server stats
immichctrl storage
immichctrl capabilities
immichctrl albums list
immichctrl albums get 00000000-0000-0000-0000-000000000001
immichctrl assets list --type image --favorite --size 20
immichctrl assets stats
immichctrl people list --with-hidden
immichctrl tags list
immichctrl duplicates
immichctrl jobs
immichctrl memories --saved
immichctrl search metadata --city Madrid --type image
immichctrl search smart "sunset over the ocean"
immichctrl server stats --json # 原始 JSON，用于管道传输
```
运行 `immichctrl help` 获取完整的命令和标志列表。退出代码：`0` 成功，`1` 运行时错误（Immich 不可达/调用失败），`2` 用法错误（未知命令/标志或错误值）。
将 `IMMICH_BASE_URL` 指向您的 Immich API，例如 `https://photos.example.com/api`（或 `http://192.0.2.10:2283/api` 用于 LAN 主机）。
### 启动 MCP 适配器
`immichctrl 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` 以搜索并在一个写入受控的步骤中创建相册。
## 安全模型
`immichctrl` 和其 MCP 适配器设计为对自动化安全：
- **读取始终允许。写入需选择加入。** 写入和删除工具仅在 `IMMICH_ALLOW_WRITES=true` 时注册。
- **破坏性调用需要明确 `confirm: true`。** 大批量更新、永久删除、合并、清空垃圾箱等工具在没有明确确认标志的情况下拒绝运行，即使启用了写入。
- **重复项解析默认为 dry-run。** 解决工具报告它们将执行的操作，然后再进行任何操作。
- **基于路径的上传仅限于指定目录。** `immich_upload_asset_from_path` 仅读取位于 `IMMICH_UPLOAD_BASE_DIR` 内的文件（解析符号链接后），如果未设置，则完全拒绝。
- **宽松的 TLS 仅限于 Immich 客户端。** `IMMICH_VERIFY_SSL=false` 仅放松 Immich 客户端的调度器；它不会削弱整个进程的证书验证。
## 为什么不选择其他选项？
- **Immich 网页界面** 是为网格浏览而构建的。它非常适合浏览，但不适合重复的操作工作流。
- **Immich CLI** 从脚本上传和管理资产，但它不是 MCP 适配器，LLM 无法调用它作为输入工具。 `immichctrl` 专注于操作员读取，而 `immichctrl mcp` 和 `immich-mcp` 提供 MCP 调用接口，供代理使用。
- **其他 Immich MCP 服务器** 通常涵盖基础知识（浏览、搜索、相册）。这个服务器更广泛：74 个工具，涵盖记忆、运动照片堆栈、校验和安全解析、垃圾审计和作业控制，并内置两级写入保护。
- **编写自己的胶水围绕 Immich REST API** 是可行的，但您需要重新实现模式验证、分页、写入门控、确认守卫和重复数据删除安全逻辑，而这些逻辑已经在该服务器中提供和测试。
## 这包是什么？
- 它 **不是** Immich 的替代品。您仍然运行自己的 Immich 服务器；这连接 AI 客户端到它。
- 它 **不是** 一个托管服务。CLI 在本地运行，MCP 适配器通过 stdio 启动，由您的 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
连接信息
猜你喜欢
暂无推荐服务器