Zotero MCP服务

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。
• 无矢量数据库 --在典型的库大小（<100K论文）下，通过 Accelerate.framework （cblas/vDSP）足够快。没有ChromaDB开销。
• 学术搜索 -集成OpenAlex API（250M+篇论文），用于外部文献发现和引用跟踪。

特性

• 关键词搜索 --通过Zotero的本地SQLite按标题、创建者、标签搜索
• 语义搜索 -使用MLX嵌入按意义查找论文（本地，无API密钥）
• 学术搜索 --搜索外部文献，获取论文元数据，跟踪引文（OpenAlex）
• ORCID导入 --从ORCID获取出版物，使用dedup批量导入Zotero
• 全球DOI决议 --覆盖所有12个内政部注册机构的级联解析器
• 写入操作 -创建集合，按DOI添加项目，管理库（Zotero Web API）
• 注释和注解 --阅读项目注释和PDF亮点/评论
• 元数据检索 --获取完整的书目信息、DOI查找、附件路径
• 收藏和标签 --浏览库结构
• 持久嵌入 --语义搜索索引在服务器重启后仍然存在

建筑

┌─────────────────────────────────────┐
│  Zotero SQLite (read-only)          │
│  ~/Zotero/zotero.sqlite            │
└──────────────┬──────────────────────┘
               │
       ┌───────┴────────┐
       │                │
  Keyword Search   Semantic Search
  (SQL queries)    (MLXEmbedders on Apple Silicon GPU)
       │                │
       │           Accelerate.framework
       │           (vDSP cosine similarity)
       │                │
       │           SQLite Persistence
       │           (~/.che-zotero-mcp/embeddings.sqlite)
       │                │
       └───────┬────────┘
               │
         MCP Server (stdio)
               │
       ┌───────┴────────┐
       │                │
  Zotero Tools     Academic Tools
  (10 tools)       (5 tools, OpenAlex API)

依赖项

• MCP Swift SDK --MCP协议
• MLXEmbedders --Apple Silicon上的本地嵌入
• OpenAlex API -学术文献搜索（免费，无API密钥）

安装

Claude 代码命令行界面

# Read-only mode (no API key needed)
claude mcp add --scope user --transport stdio che-zotero-mcp -- ~/bin/CheZoteroMCP

# Read + Write mode (with Zotero API key for creating items/collections)
claude mcp add --scope user --transport stdio -e ZOTERO_API_KEY=your_key che-zotero-mcp -- ~/bin/CheZoteroMCP

获取Zotero API密钥：https://www.zotero.org/settings/keys/new（启用库读/写访问）

工具（50）

佐特罗图书馆——阅读（14）

组库支持：大多数读/写工具都接受可选 group_id 参数。使用 zotero_list_groups 要查找可用组，请通过 group_id 搜索、浏览或写入特定组库。省略 group_id 使用您的个人库（默认）。

Zotero库-写（10，需要 ZOTERO_API_KEY)

学术搜索与分析（6）

出版物导入和参考决议（3）

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）

支持所有三种输入模式：单一 item_key，多个 item_keys，或全部 collection_key.

biblatex apa。bib出口：使用 che-biblatex-mcp (bib_normalize)用于.bib文件管理和APA格式规范化。

配置（2）

配置存储在 ~/.che-zotero-mcp/config.json 并在服务器重新启动时持续存在。AI助手可以通过以下方式读取存储的值 zotero_get_config 并明确地将它们传递给其他工具。

图引擎——知识图（13）

图形数据保留到 ~/.che-zotero-mcp/graph.bin 使用具有字符串表重复数据删除功能的自定义二进制格式。服务器启动时自动加载。

工具消除歧义指南

所有工具描述都包括范围标签([YOUR LIBRARY], [EXTERNAL DATABASE], [BRIDGE], [WRITE])以及交叉引用，以防止人工智能选择错误的工具。

常见的模糊请求和正确的工具选择：

数据源

每个工具都连接到三个数据源之一。了解这一点有助于解决以下问题 database is locked.

按数据源列出的工具

常见问题

• 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）

版本历史记录

致谢

• 54年/月 --启发这个项目的原始Python实现
• 颜色套件 --Swift中MLXEmbedders+混合搜索的参考
• MLXEmbedders --苹果官方Swift嵌入模型
• OpenAlex --免费开放的学术元数据目录

许可证

麻省理工学院