photo-archive-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
把手机里的实验照片,归档成可追溯的科研知识库。
扫描 → 网页勾选 → 重命名归档 → 索引核对,全程本地跑;17 个 MCP 工具,直接接进 Claude、Cursor、Codex 等客户端。
为什么会有这个项目
实验做久了,手机相册里会堆几千张照片:现场实拍、仪器读数、谱图、表格截图、微信传输图混在一起。想写论文的时候翻半天找不到,找到了也说不清是哪天、哪批样品。
photo-archive-mcp 把这些照片整理成目录 = 日期 + 当日总结、文件名 = 日期 + 内容标签 + 编号的结构化归档,同时生成清单、索引、对比报告和入库映射。之后写论文、复盘、交材料,按日期或关键词都能直接搜到。
Related MCP server: FilePilot AI
它会做什么
你做实验时的痛 | 这个工具的处理 |
相册里几千张图,挑不过来 | 单文件「勾选网页」:缩略图预览、按日期/相册/大小/损坏状态筛选、框选批量勾选,离线可用 |
文件名没有任何信息 | 自动重命名成 |
说不清当天拍了什么 | 读图理解交给上层 Agent 或人工,结论写进计划的 |
重复、损坏混在一起 | 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 个工具
阶段 | 工具 | 作用 |
取图 |
| Windows 走 MTP/WPD 断点续传;macOS/Linux 复制本地照片目录 |
扫描 |
| 递归扫描:日期、相册、尺寸、指纹、解码状态、重复与损坏清单 |
勾选 |
| 生成内联数据的单文件勾选网页,可导出/导入勾选状态 |
计划 |
| 合并勾选清单与标签,生成归档计划;dry-run 只出目录树 |
归档 |
| 按日期建目录、重命名、复制、写清单/索引/对比报告,支持增量 |
核对 |
| 清点文件夹数、图片数、体积、清单索引是否齐全 |
检索 |
| 按关键词/日期/标签反查;生成入库 commit message 草稿 |
选片 |
| 按文件名/相册规则给标签建议,合并历史词表 |
治理 |
| 压缩副本、模糊/过暗/过亮筛查、论文配图清单 |
衔接 |
| 跨实验台账、台账检索、知识库入库路径映射 |
完整参数、数据格式与边界见 完整手册。
设计上的几个取舍
不做 AI 读图:判断照片内容需要多模态模型,各家客户端本来就有;本服务只负责可验证、可重复的确定性整理,避免"看起来整理好了、其实对不上"。
默认复制,不移动源文件:归档目录和手机克隆目录互不影响,有对照表可回滚。
不直接写远程仓库:归档在本地完成,是否入库、何时推送由你决定。
所有产物都是纯文本 JSON/Markdown:方便 diff、git 管理和后续再加工。
文档
完整使用手册(中文):分步详解、工具参数、数据格式、命名规则、配置项、边界说明
隐私与安全
照片和元数据只在本机处理,服务本身不发起网络请求、不上传任何文件。
仓库内不含作者私人信息;示例与测试用合成图片,路径均为占位符。
安全问题和敏感数据相关的报告方式见 SECURITY.md。
许可与声明
本仓库代码:MIT。可商用、修改、再分发,保留版权与许可声明即可。
第三方依赖(均为宽松许可,与 MIT 兼容;本项目不打包、不修改其源码):
仓库素材:
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.pyLicense
MIT © gaoanze
如果这个工具帮你省下了整理实验照片的时间,点个 ⭐ 就是最大的支持;也欢迎把这套归档流程推荐给同组同学。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Your personal library, readable by AI agents: durable snapshots, hybrid search, 46 MCP tools.
Unofficial Archive MCP — wraps the Internet Archive APIs (free, no auth)
12 Binary/Forensics MCP tools: entropy triage, ELF/PE/WASM disasm, PCAP, EXIF, SQLite, ZIP.
121Provenance and metadata tools for AI agents. Paid tools use x402 (USDC) at /mcp/<tool>.
Related MCP Servers
- AlicenseAqualityBmaintenanceConverts 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.37MIT
- AlicenseNot gradedqualityCmaintenanceLocal-first MCP server for safely searching, reading, summarizing, tagging, deduplicating, and organizing local files with scoped access, read-only defaults, and dry-run plans.19MIT
- AlicenseNot gradedqualityCmaintenanceLocal-first MCP server for indexing and searching research materials (papers, notes, logs, READMEs) using SQLite FTS, with tools for memory management and evidence retrieval.MIT
- AlicenseAqualityBmaintenanceA 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.6MIT