che-zotero-mcp
A. macOS原生 Zotero的MCP服务器，内置于Swift中。将您的研究库与AI助手连接起来——关键字搜索、语义搜索、学术文献发现、引文跟踪——所有这些都在Apple Silicon上本地运行。
受启发于 54年/月 （Python），重新构想为原生macOS应用程序。
为什么要进行原生重写？
| 佐特罗mcp python che-zotero-mcp （Swift） | ||
|---|---|---|
| 语言 | Python | Swift |
| 嵌入 | 句子转换器（PyTorch） | MLXEmbedders（苹果MLX框架） |
| 默认模型 | 全MiniLM-L6-v2（仅限英语，384昏暗） | BAAI/bge-m3（多语言，1024昏暗） |
| 向量数据库 | ChromaDB（独立进程） | 内存+加速框架+SQLite持久化 |
| Zotero接入 | pyzotero HTTP客户端+SQLite | 直接SQLite（只读） |
| 依赖项 | ~12个软件包（chromadb、torch、openai等） | 2个Swift软件包（MCP SDK、MLX） |
| 运行时 | Python+pip/uv | 单编译二进制 |
| GPU加速 | CUDA/CPU回退 | 苹果硅GPU（金属） |
| 外部服务 | 可选（OpenAI，Gemini用于嵌入） | OpenAlex用于学术搜索（免费，无API密钥） |
| 平台 | 跨平台 | 仅限macOS（苹果硅） |
关键区别
- 零Python依赖 --没有pip，没有venv，没有PyTorch。一个二进制文件，立即运行。
- 苹果硅原生 --MLX通过Metal直接在GPU/神经引擎上运行嵌入，而不是通过PyTorch。
- 无矢量数据库 --在典型的库大小（\ 组库支持：大多数读/写工具都接受可选
group_id参数。使用zotero_list_groups要查找可用组，请通过group_id搜索、浏览或写入特定组库。省略group_id使用您的个人库（默认）。
Zotero库-写（10，需要 ZOTERO_API_KEY)
| 工具 | 说明 |
|---|---|
zotero_create_collection | 创建新集合（幂等） |
zotero_add_item_by_doi | DOI添加纸张（OpenAlex自动填充，幂等） |
zotero_create_item | 创建具有显式字段的项（如果DOI提供，则幂等） |
zotero_add_to_collection | 将现有项目添加到集合中 |
zotero_delete_item | 按键删除项目 |
zotero_add_attachment | 通过Web API文件上传上传本地文件（PDF、EPUB等）作为附件 |
zotero_delete_collection | 删除收集容器（保留其中的项目） |
zotero_normalize_titles | 批次标题案例→ 保留专有名词的句子格（支持dry_run） |
zotero_set_in_my_publications | 在“我的出版物”中添加/删除项目(inPublications 旗帜） |
zotero_find_duplicates | 检测并合并重复项（扫描→ 确认→ 合并工作流） |
学术搜索与分析（6）
| 工具 | 说明 |
|---|---|
academic_search | 搜索外部文献（OpenAlex，2.5亿多篇论文） |
academic_lookup_doi | 通过DOI获取完整的论文元数据 |
academic_get_citations | 正向引文追踪 |
academic_get_references | 反向参考跟踪 |
academic_search_author | 按作者搜索论文（ORCID>作者ID>姓名） |
academic_compare_papers | 11维相似向量（语义、bib耦合、Adamic Adar、RA、HPI、HDI、共引、作者、地点、标签、最短路径） |
出版物导入和参考决议（3）
| 工具 | 说明 |
|---|---|
orcid_get_publications | 从ORCID ID获取公共出版物 |
import_publications_to_zotero | 从ORCID、OpenAlex、DOI列表或参考元数据批量导入（支持模拟运行） |
resolve_references | 通过CrossRef+OpenAlex将部分参考元数据（标题、作者、年份、ISSN）解析为DOI |
DOI决议使用可信度优先的级联回退：DOI.org（发布者提交）→ 交叉参考REST API→ OpenAlex（聚合）→ Airiti DOI（区域），涵盖所有12个全球DOI注册机构。
CV/参考文献导入
从简历、参考文献列表或任何非结构化来源导入出版物：
AI reads CV PDF → extracts references → import_publications_to_zotero(source='references', references=[...])- 有DOI → 导入完整的元数据（摘要、引用等）
- 没有DOI，但有标题+作者 → CrossRef/OpenAlex反向查找查找DOI
- 真的没有 → 从原始元数据（标题、作者、年份、期刊）创建
- 模棱两可的匹配 → 跳过手动消歧建议
resolve_references 可以在导入前单独使用进行预览。 import_publications_to_zotero(source='references') 将resolve和import组合在一个调用中。
引文格式（1）
| 工具 | 说明 |
|---|---|
zotero_to_apa | 将项目转换为APA第7版文本（参考/引文/参考列表） |
支持所有三种输入模式：单一 item_key，多个 item_keys，或全部 collection_key.
biblatex apa。bib出口：使用che-biblatex-mcp(bib_normalize)用于.bib文件管理和APA格式规范化。
配置（2）
| 工具 | 说明 |
|---|---|
zotero_set_config | 存储持久键值配置（例如。 my.orcid, researchers.advisor.name) |
zotero_get_config | 读取配置值（单键或全部） |
配置存储在 ~/.che-zotero-mcp/config.json 并在服务器重新启动时持续存在。AI助手可以通过以下方式读取存储的值 zotero_get_config 并明确地将它们传递给其他工具。
图引擎——知识图（13）
| 工具 | 说明 |
|---|---|
graph_import_from_zotero | 将Zotero库导入到图表中（消除重复的作者/期刊，累积合著者权重） |
graph_stats | 图形统计：按类型划分的节点/边计数，按程度划分的顶部节点 |
graph_add_node | 创建节点（研究员、论文、机构、期刊） |
graph_add_edge | 创建边（已授权、CO_AUTHOR、已发布、附属、CITES、ADVISOR_OF） |
graph_remove_node | 删除节点及其所有边 |
graph_remove_edge | 移除边缘 |
graph_save | 将图形持久化为二进制文件(~/.che-zotero-mcp/graph.bin) |
graph_neighbors | 使用可选的边缘类型和方向过滤器查找邻居 |
graph_shortest_path | 两个节点之间的BFS最短路径 |
graph_co_author_stats | 共享论文数的合著者分析 |
graph_citation_network | 递归引用树（参考文献+引用人） |
graph_community | 具有可配置跳数限制的BFS社区检测 |
graph_query | 简化密码查询（MATCH/WHERE/RETURN） |
图形数据保留到 ~/.che-zotero-mcp/graph.bin 使用具有字符串表重复数据删除功能的自定义二进制格式。服务器启动时自动加载。
工具消除歧义指南
所有工具描述都包括范围标签([YOUR LIBRARY], [EXTERNAL DATABASE], [BRIDGE], [WRITE])以及交叉引用，以防止人工智能选择错误的工具。
常见的模糊请求和正确的工具选择：
| 用户说 | 意图 | 正确的工具 | 不是这个 |
|---|---|---|---|
| “我有这张纸吗？” | 检查现有的图书馆 | zotero_search / zotero_search_by_doi | ~~学术研究~~ |
| “查找关于X的论文” | 发现新的研究 | academic_search | ~~zotero_search~~ |
| “DOI 10.xxx是什么？” | 查找论文信息 | academic_lookup_doi | ~~zotero_search_by_doi~~ |
| “此DOI是否在我的库中？” | 检查是否已保存 | zotero_search_by_doi | ~~学术研究~~ |
| “保存此文件” | 添加到Zotero | zotero_add_item_by_doi | ~~学术研究~~ |
| “史密斯博士的论文” | 作者探索 | academic_search_author | ~~zotero_search~~ |
| “我读过关于X的什么？” | 从图书馆回忆 | zotero_semantic_search | ~~学术研究~~ |
数据源
每个工具都连接到三个数据源之一。了解这一点有助于解决以下问题 database is locked.
| 数据源 | 连接 | 需要 | 故障模式 |
|---|---|---|---|
| 本地SQLite | ~/Zotero/zotero.sqlite （只读） | 已安装Zotero | database is locked Zotero同步/写入时 |
| Zotero Web API | api.zotero.org | ZOTERO_API_KEY +internet | 网络错误、身份验证失败 |
| OpenAlex API | api.openalex.org | Internet（无API密钥） | 网络错误，速率限制 |
按数据源列出的工具
| 工具 | 来源 | 注释 |
|---|---|---|
zotero_get_my_publications | 本地SQLite→ Zotero Web API | 数据库锁定时自动回拨 |
zotero_search | 本地SQLite | |
zotero_get_metadata | 本地SQLite | |
zotero_get_collections | 本地SQLite | |
zotero_get_tags | 本地SQLite | |
zotero_get_recent | 本地SQLite | |
zotero_get_items_in_collection | 本地SQLite | |
zotero_search_by_doi | 本地SQLite | |
zotero_get_attachments | 本地SQLite | 返回本地文件路径 |
zotero_get_notes | 本地SQLite | |
zotero_get_annotations | 本地SQLite | |
zotero_semantic_search | 本地SQLite+内存索引 | 运行 zotero_build_index 首先 |
zotero_build_index | 本地SQLite→ 本地嵌入 | 在Apple Silicon GPU上使用MLX |
zotero_create_collection | Zotero Web API | 需要 ZOTERO_API_KEY |
zotero_add_item_by_doi | Zotero Web API+OpenAlex | 来自OpenAlex的元数据，通过API编写 |
zotero_create_item | Zotero Web API | 需要 ZOTERO_API_KEY |
zotero_add_to_collection | Zotero Web API | 需要 ZOTERO_API_KEY |
zotero_add_attachment | Zotero Web API+S3 | 将本地文件作为附件上传 |
zotero_delete_item | Zotero Web API | 需要 ZOTERO_API_KEY |
zotero_delete_collection | Zotero Web API | 需要 ZOTERO_API_KEY |
academic_search | OpenAlex API | 2.5亿篇以上论文，免费 |
academic_lookup_doi | OpenAlex API | 按DOI查找 |
academic_get_citations | OpenAlex API | 转发引用 |
academic_get_references | OpenAlex API | 反向引用 |
academic_search_author | OpenAlex API | 按作者姓名搜索 |
orcid_get_publications | ORCID API | 公开出版物 |
import_publications_to_zotero | CrossRef+OpenAlex+Zotero Web API | 带重复数据消除的批量导入；source=“references”添加了CrossRef反向查找 |
resolve_references | CrossRef+OpenAlex+PubMed | 反向查找：元数据→ DOI |
academic_compare_papers | OpenAlex API+本地SQLite | 图形度量+嵌入 |
zotero_to_apa | 本地SQLite | 将项目转换为APA 7格式的文本 |
zotero_normalize_titles | 本地SQLite+Zotero Web API | 读取本地，通过API写入 |
zotero_find_duplicates | 本地SQLite+Zotero Web API | 扫描读取本地，通过API合并写入 |
zotero_set_config | 本地文件 | ~/.che-zotero-mcp/config.json |
zotero_get_config | 本地文件 | ~/.che-zotero-mcp/config.json |
常见问题
database is locked--Zotero桌面正在积极向SQLite写入（例如同步、导入）。等待同步完成，或短暂关闭Zotero。- 写入工具返回身份验证错误 —
ZOTERO_API_KEY未设置或已过期。获取新密钥https://www.zotero.org/settings/keys/new. - 本地读取返回空 --MCP可能已重新连接并丢失SQLite路径。跑
/mcp重新连接。
需求
- macOS 14+
- Zotero 7+本地安装
- 苹果硅Mac（M1/M2/M3/M4/M5）
版本历史记录
| 版本 | 更改 |
|---|---|
| v1.17.1 | 作者搜索用户体验： academic_search_author 和 orcid_get_publications 现在建议创建Zotero收藏并批量导入论文 |
| v1.17.0 | 嵌入式图引擎：13种用于研究人员网络分析的新工具-- graph_import_from_zotero, graph_query （Cypher）、最短路径、合著者统计、引文网络、社区检测。具有自定义格式的二进制持久性。总共50个工具。 |
| v1.16.0 | 参考分辨率和CV导入： resolve_references （通过CrossRef+OpenAlex+PubMed进行反向DOI查找）， import_publications_to_zotero(source='references') 一次调用CV/参考书目导入 |
| v1.14.0 | 删除 zotero_to_biblatex_apa --biblatex apa。bib出口转移到 che-biblatex-mcp (bib_normalize)用于正确的LaTeX感知解析 |
| v1.13 | 交叉参考REST API后退DOI解析-修复返回“找不到”的IEEE/ACM论文；级联：doi.org→ 交叉引用→ OpenAlex→ Airiti |
| v1.12.0 | 我的出版物管理： zotero_set_in_my_publications --通过以下方式在Zotero的内置“我的出版物”中添加/删除项目 inPublications 旗帜 |
| v1.11.0 | 组库支持： zotero_list_groups +可选 group_id 所有读/写工具上的参数（本地SQLite+Web API） |
| v1.10.0 | 文件附件上传： zotero_add_attachment -通过Web API文件上传流程上传本地PDF/EPUB/图像到Zotero云 |
| v1.9.0 | 重复检测和合并： zotero_find_duplicates （扫描→ 确认→ 合并）、三层置信度（仅DOI/title+作者/标题）、智能初选 |
| v1.8.0 | 标题规范化： zotero_normalize_titles （批次标题案例→ 句子格）、专有名词列表（~500个术语）、句子格检测启发式、增强型 protectProperNouns |
| v1.7.0 | 引文格式： zotero_to_biblatex_apa （biblatex apa.bib）， zotero_to_apa （APA 7文本）。所有Zotero油田都暴露了。 |
| v1.6.0 | 11维图论度量相似向量， zotero_delete_collection，共引错误修复 |
| v1.5.0 | 配置系统(zotero_set_config/zotero_get_config) |
| v1.4.0版本 | zotero_get_my_publications 与当地→网络回退 |
| v1.3.3 | academic_search_author 支持ORCID/作者ID/姓名（3种标识符类型） |
| v1.3.2 | 可信度优先的DOI解决方案，重命名 academic_get_paper → academic_lookup_doi |
| v1.3.0 | 写幂等性， zotero_delete_item |
| v1.2.0 | ORCID集成，通用DOI解析器，批量导入 |
| v1.1.0 | Zotero Web API编写工具、注释和注释 |
| v1.0.0 | 学术搜索（OpenAlex），嵌入持久性，增强的Zotero工具 |
| v0.1.0 | 初始版本--关键字搜索、语义搜索、基本Zotero工具 |
致谢
- 54年/月 --启发这个项目的原始Python实现
- 颜色套件 --Swift中MLXEmbedders+混合搜索的参考
- MLXEmbedders --苹果官方Swift嵌入模型
- OpenAlex --免费开放的学术元数据目录
许可证
麻省理工学院