claw2mmich
claw2immich是一个Python MCP(模型上下文协议)服务器,用于公开选定的Imich REST API端点。它为API元数据使用了Immith OpenAPI规范,并为常见的只读检查提供了一个小型的许可软件工具集。
状态
- 实现了核心MCP服务器和能力过滤。
- 工具公开由Immich API权限控制。
- 集成测试包括工具列表和权限探测。
可用工具
ping_serverget_server_versiontool_access_reportwrite_capability_reportget_current_user(仅在API密钥/令牌允许的情况下)downloadAsset(仅当配置了API密钥/令牌时;返回transport-safebase64有效载荷和支持可选immich_link交付模式)
所有OpenAPI端点都作为名为 immich_ 或 immich__.
工具根据身份验证存在、仅限管理员的标记和写入能力探测进行筛选(默认 POST /api/assets).
OpenAPI工具描述包括:
params:所需路径/查询/正文字段摘要example:所需输入的简短调用草图returns:响应模式标题和关键字段(如果可用)
OpenAPI工具对资产、相册、人物和地点的响应包括 web_url 字段,直接链接到Immich web UI中的项目(当 IMMICH_EXTERNAL_DOMAIN 从服务器设置中配置或发现)。
OpenAPI工具参数使用显式的前缀字段,因此MCP客户端可以发现要设置的内容:
path_用于路径参数query_查询参数header_对于标头参数cookie_cookie参数body对于JSON请求体
遗留字段 path_params, query_params, headers,以及 json_body 仍然接受兼容性。
downloadAsset 适用于无法直接访问Imich API密钥的客户端。默认交付模式为 shared_link:当Immich shared-links API支持时,服务器返回一个短时间的标记化链接(30分钟),没有内联有效负载数据。为了MCP JSON安全,内联有效载荷交付(inline_base64)保持base64编码。可选兼容模式 immich_link 返回一个经过直接身份验证的Immich URL。
MCP文件表面
- 服务器指令在初始化过程中发送。将它们用作短入口,并指向使用指南资源。
- 初始化指令现在调用externalDomain发现、工作流组、做/不做指南和示例指令字符串。
- 资源:
docs://usage-guide包含详细的工作流程指南和示例。 - 提示:工作流模板的标题包括“Immich:获取图像”、“Immich:Find person”和“Immich:Share相册”。
配置
环境变量:
IMMICH_BASE_URL(默认值http://localhost:2283)IMMICH_API_KEYIMMICH_API_TOKENIMMICH_EXTERNAL_DOMAIN(可选:用于web UI链接的域,如https://immich.example.com;如果未设置,则从以下位置发现/api/server-config)IMMICH_PROFILE(可选:read_only,read_write,或full_scope)IMMICH_WRITE_PROBE_PATH(默认值/api/assets)IMMICH_WRITE_PROBE_METHOD(默认值POST)IMMICH_DOWNLOAD_ASSET_DELIVERY(可选:shared_link(默认),inline_base64,或immich_link)
MCP服务器环境变量:
MCP_TRANSPORT(stdio,sse,或streamable-http;默认stdio)MCP_HOST(默认值127.0.0.1)MCP_PORT(默认值8000)MCP_MOUNT_PATH(SSE传输的可选安装路径)MCP_LOG_LEVEL(默认值INFO)
OpenAPI规范来源:
版本匹配规范(之后 /api/health 和 /api/server/version):
https://raw.githubusercontent.com/immich-app/immich/v{VERSION}/open-api/immitch-openapi-specs.json
访问配置文件
访问配置文件提供了预定义的权限级别,以简化API密钥管理并降低错误配置风险。集 IMMICH_PROFILE 为以下值之一:
read_only
使用案例: 安全浏览、搜索和报告,无修改风险。
所需权限:
asset.read-查看照片和视频album.read-查看相册library.read-浏览库timeline.read-访问时间线和记忆
暴露的典型工具:
immich_getAllAssets,immich_getAssetById,immich_searchAssetsimmich_getAllAlbums,immich_getAlbumInfoimmich_getMyUserInfo,immich_getServerVersion- 用于读取数据的所有GET端点
堵塞的工具:
- 资产上传、更新、删除
- 相册创建、修改
- 用户管理
- 服务器配置
Claude桌面配置示例(mcporter.json 片段):```json
{
"mcpServers": {
"claw2immich-readonly": {
"command": "python",
"args": ["c:\path\to\claw2immich\main.py"],
"env": {
"IMMICH_BASE_URL": "https://immich.example.com",
"IMMICH_API_KEY": "your-read-only-key",
"IMMICH_PROFILE": "read_only"
}
}
}
}
### `read_write`
**使用案例:** 无管理员权限的完整资产和相册管理。
**所需权限:**
- 全部 `read_only` 权限加:
- `asset.create` -上传照片/视频
- `asset.update` -编辑元数据,收藏夹
- `asset.delete` -删除资产
- `album.create` -创建相册
- `album.update` -修改相册
- `album.delete` -删除相册
**暴露的典型工具:**
- 所有只读工具加上:
- `immich_uploadAsset`, `immich_updateAsset`, `immich_deleteAssets`
- `immich_createAlbum`, `immich_addAssetsToAlbum`, `immich_removeAssetFromAlbum`
- `immich_updateUser` (仅限自己的用户)
- 除管理员外的所有POST、PUT、PATCH、DELETE端点
**堵塞的工具:**
- 用户管理(`getAllUsers`, `createUser`, `deleteUser`)
- 服务器配置(`setServerConfig`, `updateServerConfig`)
- 系统维护(`runJobs`, `validateStorage`)
- API密钥管理
**Claude桌面配置示例:**```json
{
"mcpServers": {
"claw2immich-readwrite": {
"command": "python",
"args": ["c:\\path\\to\\claw2immich\\main.py"],
"env": {
"IMMICH_BASE_URL": "https://immich.example.com",
"IMMICH_API_KEY": "your-readwrite-key",
"IMMICH_PROFILE": "read_write"
}
}
}
}
full_scope
使用案例: 管理任务、用户管理、服务器配置。
所需权限:
- 全部
read_write权限加: admin.user-用户管理admin.config-服务器配置admin.jobs-作业管理admin.apiKey-API密钥管理
暴露的典型工具:
- 所有read_write工具以及:
immich_getAllUsers,immich_createUser,immich_updateUser,immich_deleteUserimmich_getServerConfig,immich_updateServerConfigimmich_getAllJobs,immich_runJobimmich_createApiKey,immich_updateApiKey,immich_deleteApiKey
Claude桌面配置示例:```json
{
"mcpServers": {
"claw2immich-admin": {
"command": "python",
"args": ["c:\path\to\claw2immich\main.py"],
"env": {
"IMMICH_BASE_URL": "https://immich.example.com",
"IMMICH_API_KEY": "your-admin-key",
"IMMICH_PROFILE": "full_scope"
}
}
}
}
### 无配置文件(默认)
当 `IMMICH_PROFILE` 未设置,工具筛选仅依赖于功能探测和API密钥的实际权限。这与现有配置向后兼容。
**配置文件选择指南:**
- 使用 `read_only` 用于无需修改即可执行搜索和分析的AI助手
- 使用 `read_write` 用于一般资产和相册管理工作流
- 使用 `full_scope` 仅当需要管理权限时
- 始终为每个配置文件创建具有最小权限的专用Imich API密钥
## 跑```
python main.py
帮助脚本:智能搜索CLI
要在没有MCP客户端设置的情况下进行快速本地调试,请使用辅助脚本:```sh
python helper/smart_search_cli.py --list-envs
python helper/smart_search_cli.py --env .env --query "golden retriever on beach" --size 25 --order desc
行为:
- 可用列表 `.env` 当前目录中的文件(`.env`, `.env_*`).
- 负载 `IMMICH_BASE_URL` 和 `IMMICH_API_KEY` 或 `IMMICH_API_TOKEN` 从所选的env文件中。
- 呼叫 `POST /api/search/smart` 并将JSON响应直接打印到stdout。
## 测试
集成测试使用标准库 `unittest` runner(pytest也可以发现它们)。
被阻止的工具原因现在包括HTTP状态或网络错误详细信息,以帮助排除功能检查故障。
集成测试设置:
1. 确保Immich服务器正在运行且可访问。
1. 创建 `.env_test` 使用只读凭据。
1. 创建 `.env` 具有完全访问凭据,或已设置 `IMMICH_ENV_FULL` 到另一个文件。
MCP客户端测试使用SSE启动后台服务器。您可以覆盖默认值:
- `MCP_TEST_HOST` (默认值 `127.0.0.1`)
- `MCP_TEST_PORT` (默认值 `0` 用于自动分配)
- `MCP_TEST_TIMEOUT` (默认值 `20` 秒)
- `MCP_LOG_LEVEL` (默认值 `DEBUG` 用于测试服务器日志)
运行:```
python -m unittest discover -s tests -v
pytest可选:```
pytest tests/
您可以覆盖env文件位置:
- `IMMICH_ENV_TEST` 对于受限凭据文件(默认 `.env_test`)
- `IMMICH_ENV_FULL` 对于完全访问凭据文件(默认 `.env`)
### URL访问集成测试(`test_integration_url_access.py`)
确认 `web_url` URL装饰层生成的字段是可访问的
针对实时Immich实例(除了需要会话登录凭据外,还需要
API密钥)。
创建 `.env_web` 在项目根目录中(不包括 `.gitignore`):```
IMMICH_BASE_URL=https://your-immich.example.com
IMMICH_API_KEY=
IMMICH_EMAIL=
IMMICH_PASSWORD=
| 变量 | 目的 |
|---|---|
IMMICH_BASE_URL |
Immich实例的基本URL |
IMMICH_API_KEY |
经过身份验证的API调用的API密钥 |
IMMICH_EMAIL |
帐户电子邮件 POST /api/auth/login |
IMMICH_PASSWORD |
会话登录的帐户密码 |
IMMICH_EXTERNAL_DOMAIN 还可以被包括以覆盖URL装饰库;
如果省略,则返回到 /api/server-config 发现链。
运行:```sh
pytest tests/test_integration_url_access.py -v
测试在以下情况下自动跳过 `.env_web` 不存在,服务器无法访问,或
该实例没有该类型的数据。用以下内容覆盖文件路径 `IMMICH_ENV_WEB`:```sh
IMMICH_ENV_WEB=/path/to/other.env pytest tests/test_integration_url_access.py -v
| 测试 | 端点 | 预期URL模式 | 回归 |
|---|---|---|---|
test_asset_web_url_accessible |
GET /api/assets (回退: POST /api/search/assets) |
.../photos/{id} |
— |
test_album_web_url_accessible |
GET /api/albums |
.../albums/{id} |
— |
test_person_web_url_accessible |
GET /api/people |
.../people/{id} (不是 /photos/{id}) |
第49项 |
test_place_web_url_accessible |
GET /api/places |
.../explore... |
— |
test_newest_image_search_web_url_accessible |
POST /api/search/assets |
.../photos/{id} |
— |
test_random_person_web_url_accessible |
GET /api/people (随机选择) |
.../people/{id} |
— |
test_random_album_web_url_accessible |
GET /api/albums (随机选择) |
.../albums/{id} |
— |
test_random_video_web_url_accessible |
POST /api/search/assets 类型=视频(随机选择) |
.../photos/{id} |
— |
码头工人
在本地构建和运行
使用Docker Compose构建和运行:```
docker compose build
docker compose up
注意:容器运行 `main.py`,进口 `claw2immich` 包裹。
如果更改包布局,请重建图像,使更新的包
复制到容器中。
环境变量从shell或 `.env` 文件:
- `IMMICH_BASE_URL` (默认值 `http://host.docker.internal:2283`)
- `IMMICH_API_KEY`
- `IMMICH_API_TOKEN`
- `IMMICH_WRITE_PROBE_PATH` (默认值 `/api/assets`)
- `IMMICH_WRITE_PROBE_METHOD` (默认值 `POST`)
Docker Compose的MCP服务器设置:
- `MCP_TRANSPORT` (默认值 `sse` 作曲;使用 `streamable-http` 对于HTTP)
- `MCP_HOST` (默认值 `0.0.0.0` 组成)
- `MCP_PORT` (默认值 `8000`;作为主机端口发布)
### 使用GitHub容器注册表中的预构建映像
每次推送时,预构建的Docker镜像都会自动发布到GitHub容器注册表(GHCR) `main` 和 `develop` 分支机构,以及发布。
**拉取图像:**```bash
# Latest build from main branch
docker pull ghcr.io/joeru/claw2immich:latest
# Latest build from develop branch
docker pull ghcr.io/joeru/claw2immich:develop
# Specific version (e.g., 0.1.0)
docker pull ghcr.io/joeru/claw2immich:0.1.0
运行映像:```bash
docker run -e IMMICH_BASE_URL=https://immich.example.com \
-e IMMICH_API_KEY=your-api-key \
-p 8000:8000 \
ghcr.io/joeru/claw2immich:latest
**使用SSE传输(HTTP)运行:**```bash
docker run -e IMMICH_BASE_URL=https://immich.example.com \
-e IMMICH_API_KEY=your-api-key \
-e MCP_TRANSPORT=sse \
-e MCP_HOST=0.0.0.0 \
-p 8000:8000 \
ghcr.io/joeru/claw2immich:latest
使用只读配置文件运行:bash
docker run -e IMMICH_BASE_URL=https://immich.example.com \
-e IMMICH_API_KEY=your-readonly-api-key \
-e IMMICH_PROFILE=read_only \
-p 8000:8000 \
ghcr.io/joeru/claw2immich:latest
映像支持多种架构(amd64、arm64),并根据您的平台自动选择。
