claw2immich (Joe Ru)

MCP开发工具

提供方 JoeRu

开发工具 stdio · 本地进程 会话登录 社区 / 第三方 Claude
查看接入方式

claw2immich是一个Python MCP服务器,提供对Immich REST API的受控访问,支持只读操作、资产管理及权限过滤功能,适用于照片管理系统的集成开发。

一句话选型结论

按资料字段整理

claw2immich (Joe Ru) 属于开发工具类 MCP 服务器,stdio · 本地进程,会话登录,可直接接入 Claude,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类开发工具 传输方式stdio · 本地进程 鉴权会话登录 部署方式本地部署
GitHub 星标 4 仓库热度,无公开仓库时显示未标注
工具数 6 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

开发工具
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量6暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

API代理Python本地部署照片管理权限控制REST接口开发工具

安装与配置

stdio · 本地进程 会话登录
客户端在本机拉起子进程,数据不出本机
python main.py

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Python,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 6 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
代码与仓库操作

在对话里直接查代码、提 issue、走 PR,省掉来回切工具。

本地命令与脚本

把构建、测试、格式化这类重复命令交给模型执行。

接口联调与测试

让模型调你的接口、跑一遍用例,快速定位问题。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 6 个工具,职责相对集中,接入后不容易误操作。
  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好会话登录对应的凭据,并按最小权限配置。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在开发工具场景里让模型直接调用外部能力的人。
  • 已经在用 Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
claw2immich (Joe Ru)当前 6 stdio · 本地进程 本地部署 有 2026-05-17
Git 838e2ec1 12 stdio · 本地进程 本地部署 有 2026-05-17
Markitdown MCP 2c653a5f 1 stdio · 本地进程 本地部署 有 2026-05-17
JavaGuide 未标注 stdio · 本地进程 本地部署 有 2026-04-11
awesome-claude-skills 未标注 stdio · 本地进程 本地部署 有 2026-04-26
Context7 831acf40 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

开发工具
字段来自项目仓库与公开索引,中文说明由本站标注
提供方JoeRu上游标注的维护方 JoeRu
分类开发工具本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式会话登录远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · Python本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

12.4 KB
来自项目仓库与上游目录的原文,未做删改

claw2mmich

claw2immich是一个Python MCP(模型上下文协议)服务器,用于公开选定的Imich REST API端点。它为API元数据使用了Immith OpenAPI规范,并为常见的只读检查提供了一个小型的许可软件工具集。

状态

  • 实现了核心MCP服务器和能力过滤。
  • 工具公开由Immich API权限控制。
  • 集成测试包括工具列表和权限探测。

可用工具

  • ping_server
  • get_server_version
  • tool_access_report
  • write_capability_report
  • get_current_user (仅在API密钥/令牌允许的情况下)
  • downloadAsset (仅当配置了API密钥/令牌时;返回transport-safe base64 有效载荷和支持可选 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_KEY
  • IMMICH_API_TOKEN
  • IMMICH_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_searchAssets
  • immich_getAllAlbums, immich_getAlbumInfo
  • immich_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_deleteUser
  • immich_getServerConfig, immich_updateServerConfig
  • immich_getAllJobs, immich_runJob
  • immich_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),并根据您的平台自动选择。

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
claw2immich (Joe Ru) 怎么安装?

在客户端按下面的安装命令接入:python main.py。装完在客户端配置里引用同一个包或端点。

claw2immich (Joe Ru) 怎么在 Claude 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

claw2immich (Joe Ru) 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

claw2immich (Joe Ru) 需要 API Key 吗?

资料标注需要会话登录认证,使用前准备好对应凭据,并按最小权限配置。

claw2immich (Joe Ru) 支持哪些客户端?

资料标注支持 Claude;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

claw2immich (Joe Ru) 能提供哪些能力?

资料显示约 6 个工具;能力标签包括 API代理、开发工具、Python、Claude、权限控制。具体工具清单以官方文档为准。

claw2immich (Joe Ru) 需要什么运行环境?

运行时为 Python;属于本地进程,需要在本机装好运行环境。

claw2immich (Joe Ru) 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。