iphone-photo-library

iPhone Photo Library · MCP

通过自然语言寻找 iPhone 照片，核对后复制到文件夹。

A local photo search and copy-export workflow for MCP clients, with Windows iPhone import.

这是一个开发预览版：Windows 通过 USB 读取已信任的 iPhone 静态照片，CLIP 在本地建立内容索引，Codex 等 MCP 客户端查看候选并归档。也支持直接索引爱思助手导出的照片目录。

能做什么

• 从已连接、解锁、信任此电脑的 iPhone 复制静态图片；支持小样本与增量导入。
• 按画面内容检索本地照片，支持 JPEG、PNG、HEIC、WebP 等格式。
• 生成 HTML 预览与编号联系表，便于核对角色、插画、截图。
• 记录确认标签和排除项，供后续同名查询使用。
• 将指定图片复制到新文件夹，保留原图，避免同名冲突，校验 SHA-256 并生成来源清单。
• 提供 8 个 stdio MCP 工具和配套技能。

例如：

在我的照片库里找明日方舟相关图片，核对后复制到单独文件夹。

找初音未来的图片。

找海边日落的照片。

角色检索返回相似候选，需要核对；它不是可以保证找全的角色分类器。

快速开始

需要 Windows 10/11、Python 3.11–3.13，以及能正常识别手机的苹果设备驱动。本次实测环境是 Windows + Python 3.13；其他组合尚未逐一验证。

下载源码并进入项目目录，在 PowerShell 执行：

# 创建独立环境、安装依赖、下载约 154 MB 模型
.\setup.ps1

# 如需自动注册到 Codex，在安装时加此选项
.\setup.ps1 -RegisterCodex

脚本会生成这台电脑专用的 mcp.local.json。其他支持 stdio 的 MCP 客户端可使用其中的服务器配置。mcp.example.json 是手动配置模板，需要替换路径。移动项目后需要更新配置。

-RegisterCodex 会增加或更新同名的本地 Codex MCP 配置；普通安装不会修改 Codex 配置。若 PowerShell 的执行策略禁止运行脚本，可以在终端手动执行下列 Python 命令安装依赖，不需要修改系统安全设置：

python -m venv .venv
& .\.venv\Scripts\python.exe -m pip install -r requirements.txt
& .\.venv\Scripts\python.exe -X utf8 photo_library.py download-model

导入、搜索、归档

手机用数据线连接并解锁，在手机上信任此电脑。先导入一小批：

.\import_iphone.ps1 -MaxPhotos 120 -PerFolder 10 -MaxGB 2
& .\.venv\Scripts\python.exe -X utf8 photo_library.py index .\sources\iphone
& .\.venv\Scripts\python.exe -X utf8 photo_library.py search '初音未来' --report
& .\.venv\Scripts\python.exe -X utf8 photo_library.py search '海边日落' --english 'a photograph of sunset on a beach' --report

也可以把 index 的目录替换为爱思助手已经导出的目录。导入期间请保持手机解锁。

通过 MCP 可以使用 import_iphone_photos 启动后台导入，再用 iphone_import_status 检查完成状态。初次导入默认取样，不代表完整相册。明确需要导入 Windows 能读到的全部静态图片时：

# 先检查磁盘空间；30 GB 是此次新增复制的可调整上限
.\import_iphone.ps1 -MaxPhotos 0 -PerFolder 0 -MaxGB 30

搜索返回预览和 results.json。核对后，用实际返回的图片 ID 复制：

& .\.venv\Scripts\python.exe -X utf8 photo_library.py export --results '.\data\reports\实际目录\results.json' --ids '实际图片ID' --destination .\exports --label '明日方舟'

归档只复制指定 ID，不会自动删除或移动手机原图。结果目录含 manifest.json，记录来源和文件哈希。--ids 省略时会复制当前结果页全部图片，因此应先核对整页，并在结果分页时逐页处理。

MCP 工具

工具	用途
import_iphone_photos	后台复制手机照片到本地
iphone_import_status	查询导入日志与结果
photo_library_stats	查询已索引数量与来源目录
index_photo_folder	增量索引本地图片目录
search_photos	按内容搜索并生成预览
view_photo	返回指定图片缩略图
annotate_photos	记录核对标签或排除项
export_photos	复制明确选择的图片并校验

配套技能位于 skills/iphone-photo-library/SKILL.md，描述了导入、翻译查询、分页核对和复制归档流程。

数据与隐私

• sources/ 保存复制的照片，data/ 保存索引、缩略图和预览，exports/ 保存归档副本，models/ 保存下载的模型。
• 模型推理和视觉索引在本机运行，不需要图片识别 API 密钥。
• 本地索引不等于宿主对话完全离线。 MCP 返回的文件路径、元数据、标签和被查看的缩略图会提供给客户端；如果使用云端视觉模型核对，客户端可能将这些内容发送给对应服务。
• 源码发布包不包含照片、缩略图、索引、来源清单、模型权重或虚拟环境。这些目录及本机配置已列入 .gitignore。

当前限制

• iPhone USB 导入使用 Windows 便携设备 Shell 接口，不使用爱思助手私有接口。iCloud 中未下载的原图、隐藏媒体、编辑版本和 Live Photo 配对可能不在可读目录中。
• 仅处理静态图片；GIF 只索引第一帧，视频内容索引和 Live Photo 配对尚未实现。
• CLIP 搜索分数不是识别概率，人物角色可能误选或漏选。缺少自动的逐张视觉复核器，核对由使用者或宿主模型完成。
• 除少量内置中文别名外，中文描述需要宿主转换成英文并传入 english_query。例如“明日方舟”可传入 Arknights game screenshot or character illustration。
• 日期过滤只使用 EXIF 拍摄日期；没有该信息的截图不会出现在限定拍摄日期的结果中。
• 导入中断或超过容量上限意味着覆盖不完整；检查结果中的 errors 和 limit_reached。大图库索引可用 CLI 避免客户端工具超时。

开发验证

# 不读取真实相册、不需要模型下载的行为测试
& .\.venv\Scripts\python.exe -X utf8 -m unittest -v

# MCP 握手、工具发现与预览检查；空图库也可运行
& .\.venv\Scripts\python.exe -X utf8 smoke_test_mcp.py

# 可选硬件检查：需要连接 iPhone，会尝试复制最多一张照片
& .\.venv\Scripts\python.exe -X utf8 smoke_test_mcp.py --import-check

类似项目与定位

视觉语义检索本身已有成熟方案，这个项目的重点是 Windows iPhone 导入、MCP 核对和本地复制归档流程。

项目	主要能力	与本项目的侧重点差异
Semantic Image Search MCP	CLIP、FAISS、本地照片库 MCP 搜索	文档重点是本地图库索引与检索
Apple Photos MCP	搜索、查看、导出 Apple Photos 图库	依赖 macOS Photos
rclip	跨平台命令行语义与以图搜图	重点是终端和已有本地文件
Queryable	iPhone 上离线搜索相册	属于原生 iOS 应用
ImmichMCP	对接 Immich 的搜索和相册管理	需要已有 Immich 服务

这些是能力比较与参考，不代表复制了其实现。

许可证

源码使用 MIT。依赖和模型适用各自的上游条款，详见 THIRD_PARTY_NOTICES.md。本项目与 Apple、爱思助手、OpenAI 或所举例的游戏和角色权利方没有隶属关系。