Skip to main content
Glama

把手机里的实验照片,归档成可追溯的科研知识库。

扫描 → 网页勾选 → 重命名归档 → 索引核对,全程本地跑;17 个 MCP 工具,直接接进 Claude、Cursor、Codex 等客户端。

CI License: MIT Python MCP PRs Welcome

English · 完整手册 · 反馈问题

为什么会有这个项目

实验做久了,手机相册里会堆几千张照片:现场实拍、仪器读数、谱图、表格截图、微信传输图混在一起。想写论文的时候翻半天找不到,找到了也说不清是哪天、哪批样品。

photo-archive-mcp 把这些照片整理成目录 = 日期 + 当日总结、文件名 = 日期 + 内容标签 + 编号的结构化归档,同时生成清单、索引、对比报告和入库映射。之后写论文、复盘、交材料,按日期或关键词都能直接搜到。

Related MCP server: FilePilot AI

它会做什么

你做实验时的痛

这个工具的处理

相册里几千张图,挑不过来

单文件「勾选网页」:缩略图预览、按日期/相册/大小/损坏状态筛选、框选批量勾选,离线可用

文件名没有任何信息

自动重命名成 日期-标签-序号.jpg,非法字符自动净化,编号稳定

说不清当天拍了什么

读图理解交给上层 Agent 或人工,结论写进计划的 summary / tag;工具只做确定性落地

重复、损坏混在一起

SHA-1 指纹去重、pHash 相似分组、损坏与无法解码清单

归档后回不去

对照表、回滚清单、对比报告、照片索引、按关键词/日期/标签反向检索

跨实验一团乱

跨实验台账、入库目录映射、论文配图清单(自动编号 Fig.01)

不想把实验数据传到云上

本地优先:不联网、不上传、不直接写远程仓库

演示

生成出的勾选网页(示例数据,9 张合成实验图,含 1 组近似重复、1 张无法识别日期):

勾选网页截图

快速开始

git clone https://github.com/gaoanze/photo-archive-mcp.git
cd photo-archive-mcp

python -m venv .venv
.venv\Scripts\activate          # Windows
# source .venv/bin/activate     # macOS / Linux

pip install -e .                # Windows 想从手机直连取图:pip install -e ".[phone]"

接入 MCP 客户端(stdio,命令随安装方式调整):

{
  "mcpServers": {
    "photo-archive": {
      "command": "photo-archive-mcp",
      "args": []
    }
  }
}

不想接客户端也可以直接跑命令行演示:

python examples/selftest.py                                          # 合成样例端到端自测
python examples/cli_demo.py --source ./photos --out ./archive_ready  # 生成勾选网页 + 归档
python examples/cli_demo.py --source ./photos --out ./archive_ready --lookup 谱图   # 反查归档

工作流

flowchart LR
    A["手机相册"] -->|MTP / 本地目录| B["扫描 scan_photos<br/>元数据 · 指纹 · 缩略图 · 去重"]
    B --> C["勾选网页 build_selection_page"]
    C -->|导出 JSON| D["读图理解<br/>上层 Agent / 人工"]
    D --> E["归档计划 build_archive_plan"]
    E --> F["dry-run 预览"]
    F --> G["归档 archive_photos<br/>按日期分目录 · 重命名 · 清单"]
    G --> H["核对 inspect_archive"]
    H --> I["检索 lookup_archive<br/>台账 · 配图清单 · 入库映射"]

17 个工具

阶段

工具

作用

取图

list_phone_devices · clone_phone_photos

Windows 走 MTP/WPD 断点续传;macOS/Linux 复制本地照片目录

扫描

scan_photos

递归扫描:日期、相册、尺寸、指纹、解码状态、重复与损坏清单

勾选

build_selection_page

生成内联数据的单文件勾选网页,可导出/导入勾选状态

计划

build_archive_plan · preview_archive_plan

合并勾选清单与标签,生成归档计划;dry-run 只出目录树

归档

archive_photos

按日期建目录、重命名、复制、写清单/索引/对比报告,支持增量

核对

inspect_archive

清点文件夹数、图片数、体积、清单索引是否齐全

检索

lookup_archive · draft_commit_message

按关键词/日期/标签反查;生成入库 commit message 草稿

选片

suggest_tags

按文件名/相册规则给标签建议,合并历史词表

治理

export_compressed · quality_filter · export_figures

压缩副本、模糊/过暗/过亮筛查、论文配图清单

衔接

update_ledger · query_ledger · target_mapping

跨实验台账、台账检索、知识库入库路径映射

完整参数、数据格式与边界见 完整手册。

设计上的几个取舍

  • 不做 AI 读图:判断照片内容需要多模态模型,各家客户端本来就有;本服务只负责可验证、可重复的确定性整理,避免"看起来整理好了、其实对不上"。

  • 默认复制,不移动源文件:归档目录和手机克隆目录互不影响,有对照表可回滚。

  • 不直接写远程仓库:归档在本地完成,是否入库、何时推送由你决定。

  • 所有产物都是纯文本 JSON/Markdown:方便 diff、git 管理和后续再加工。

文档

隐私与安全

  • 照片和元数据只在本机处理,服务本身不发起网络请求、不上传任何文件。

  • 仓库内不含作者私人信息;示例与测试用合成图片,路径均为占位符。

  • 安全问题和敏感数据相关的报告方式见 SECURITY.md。

许可与声明

  • 本仓库代码:MIT。可商用、修改、再分发,保留版权与许可声明即可。

  • 第三方依赖(均为宽松许可,与 MIT 兼容;本项目不打包、不修改其源码):

    • mcp(MIT)——MCP Python SDK;

    • Pillow(HPND / PIL License)——图片解码、缩略图与质量指标;

    • pywin32(PSF License,仅 Windows 取图可选)。

  • 仓库素材:assets/banner.svg 为自制;assets/demo-selection.png 由脚本生成的纯色合成示意图渲染而成,不含真实照片、字体文件或第三方图片。

  • 商标声明:Claude、Cursor、Codex 等名称仅用于说明 MCP 客户端兼容性,商标归各自所有者;本项目与 Anthropic 及 Model Context Protocol 官方无隶属关系。“微信 / WeChat”仅作为照片来源的描述性标签出现。

Roadmap

  • 连拍/视频的序列分组

  • 相似照片保留策略可配置(当前只分组不自动删)

  • 更多取图后端:Android adb、iCloud 导出目录

  • 勾选网页键盘快捷键与暗色主题

  • 导出到 Zotero / Obsidian 的引用格式

参与贡献

欢迎 issue 和 PR:先看 CONTRIBUTING.md。提交前跑一遍:

python tests/test_core.py
python examples/selftest.py

License

MIT © gaoanze


如果这个工具帮你省下了整理实验照片的时间,点个 ⭐ 就是最大的支持;也欢迎把这套归档流程推荐给同组同学。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Converts handwritten journal photos into a searchable, AI-powered local knowledge base using Tesseract OCR. It enables users to query their notes, track insights, and export data through MCP-compatible AI assistants while maintaining complete local data privacy.
      37
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Local-first MCP server for safely searching, reading, summarizing, tagging, deduplicating, and organizing local files with scoped access, read-only defaults, and dry-run plans.
      19
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      A local, read-only MCP server that lets AI agents inspect and analyze photo libraries by scanning files, aggregating EXIF stats, finding duplicates, scoring blur, and generating cull reports without uploading any data.
      6
      MIT