claw2immich (Joe Ru)

claw2mmich

](https://github.com/JoeRu/claw2immich/actions/workflows/build-docker.yml)

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 片段）：

{
  "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桌面配置示例：

{
  "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桌面配置示例：

{
  "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客户端设置的情况下进行快速本地调试，请使用辅助脚本：

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服务器正在运行且可访问。
2. 创建 .env_test 使用只读凭据。
3. 创建 .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_EXTERNAL_DOMAIN 还可以被包括以覆盖URL装饰库； 如果省略，则返回到 /api/server-config 发现链。

运行：

pytest tests/test_integration_url_access.py -v

测试在以下情况下自动跳过 .env_web 不存在，服务器无法访问，或 该实例没有该类型的数据。用以下内容覆盖文件路径 IMMICH_ENV_WEB:

IMMICH_ENV_WEB=/path/to/other.env pytest tests/test_integration_url_access.py -v

码头工人

在本地构建和运行

使用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 分支机构，以及发布。

拉取图像：

# 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

运行映像：

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）运行：

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

使用只读配置文件运行：

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），并根据您的平台自动选择。