Zoteus

_{2026 年 9 月 6 日，维护者在自己的文献库中进行的真实会话。工具调用以延时摄影形式展示。完整录像见 zoteus.com。}

安装

大多数客户端无需下载任何内容：客户端首次运行时会通过 npx 获取 Zoteus。刚接触 MCP 服务？请先阅读 docs/getting-started.md。

客户端	方式
Claude Desktop	从最新版本下载适用于你系统的安装包：zoteus-macos.mcpb、zoteus-windows.mcpb 或 zoteus-linux.mcpb，然后双击打开。这种安装方式带有设置界面（Settings → Extensions → Zoteus），并可为每个工具单独设置权限。
Claude Code	claude mcp add --transport stdio zoteus -- npx -y @oscardvs/zoteus
Claude Code，作为插件使用	/plugin marketplace add oscardvs/zoteus，然后运行 /plugin install zoteus@zoteus。包含同一个服务，另附四项研究技能，可教 Claude 引用带页码的段落、构建证据表、添加引文并整理文献库。使用 /plugin → Zoteus → Configure options 设置可选的 API 密钥。Claude Desktop 不会显示插件的设置，因此请在那里使用 .mcpb。请参阅 plugins/zoteus。
Cursor、VS Code、Zed、Codex、Gemini CLI，以及任何 MCP 客户端	运行 npx add-mcp @oscardvs/zoteus，或手动将 npx -y @oscardvs/zoteus 添加为 stdio 服务。
浏览器中的 claude.ai	添加一个自定义连接器，指向托管版 Zoteus或你自己的远程实例。
ChatGPT（网页）	需要在付费 ChatGPT 套餐中启用开发者模式（Settings → Security and login）。然后选择 Plugins → Create app，服务器 URL 填写托管版 Zoteus 的地址（https://mcp.zoteus.com/mcp），或你自己的远程实例的地址，并选择 OAuth 进行身份验证。ChatGPT 仅连接远程服务，因此 npx 安装方式不适用。

然后运行 Zotero 桌面应用。读取操作，以及在 Zotero 10+ 中对应用内所有文献库（包括你自己的文献库和同步到其中的群组文献库）的写入操作，均无需云端密钥。若要同步、访问应用中没有的群组文献库，或在应用关闭时使用，请添加 Zotero API 密钥：

claude mcp add --transport stdio zoteus -e ZOTERO_API_KEY=xxxxx -- npx -y @oscardvs/zoteus

请在 zotero.org/settings/keys 获取密钥。在桌面应用中，启用 Settings → Advanced → "Allow other applications on this computer to communicate with Zotero"。各客户端的分步说明和截图请参阅：zoteus.com/docs/connect-claude-to-zotero。

更新桌面扩展安装。 手动安装的 .mcpb（或旧版 .dxt）不会自动更新。请在扩展设置中启用 Check for updates（或设置 ZOTEUS_UPDATE_CHECK=true）。Zoteus 每天会向 GitHub 查询一次；有新版本时，会通过聊天中的 zotero_whoami 告知你；此时请下载适用于你系统的新安装包并重新安装。此检查默认关闭。npx 安装始终运行最新发布版本。

功能

Zoteus 提供一组以 zotero_* 命名的研究工具，可按关键词或含义搜索文献库、返回带页码定位信息的 PDF 段落、以图像形式显示 PDF 页面和图表、使用 citeproc-js 按任意 CSL 样式格式化参考文献、通过 DOI 或 arXiv id 添加条目，以及创建、编辑、添加标签和整理条目，并提供带版本控制的写入操作和可撤销的回收站。Zotero 桌面应用运行时，读取和写入操作会直接对应用内所有文献库执行，且无需云端 API 密钥；Zotero Web API v3 则用于同步、访问应用中没有的群组文献库，以及在应用关闭时使用。Zoteus 使用 TypeScript 编写，在你的计算机上运行，并采用 MIT 许可证。

功能特性

• 搜索自己的文库。 对标题、摘要、创作者和标签进行关键词与语义混合搜索，还能在 PDF 和笔记中进行全文关键词搜索，并返回匹配段落及其页码。你自己的笔记和 PDF 批注会按所属条目建立索引，因此“我在哪里反对过这个观点？”也是搜索可以回答的问题。设置 ZOTEUS_INDEX_FULLTEXT（或向 zotero_index 传入 fulltext:true）后，索引搜索还会涵盖配置上限内可用的 PDF 正文文本，因此即使某个论点从未出现在摘要中，也仍然能找到。
• 格式化引文。 Zoteus 会读取 Zotero 文库中的引文数据，并使用 citeproc-js 按 CSL 样式库中的任意 CSL 样式格式化引文。
• 通过标识符添加论文。 传入 DOI 或 arXiv id，Zoteus 就会获取元数据并添加条目。内置解析器开箱即用；Zotero translation-server 可扩展支持 ISBN、PMID 和 URL（参见 docs/resolver.md）。
• 写回 Zotero。 创建条目、编辑、添加标签和整理文库。写入操作采用版本控制并进行乐观锁重试；默认情况下，移至废纸篓的操作可撤销，永久删除则需主动启用并经过确认。
• 直接写入桌面应用。 添加和编辑条目、标签、分类、保存的搜索、合并、附件、批注，以及移至废纸篓和恢复操作，都会直接写入正在运行的 Zotero，无需云端 API 密钥，适用于你自己的文库及应用中打开的任何群组文库。在 Zotero 10+ 中，这使用本地 API，只需授予一次密钥权限（“Always Allow”）；在 Zotero 9 及更早版本中，由于本地 API 只读，添加条目和批注会使用浏览器扩展所用的连接器协议。对于应用中未打开的群组文库，以及应用未运行时，则回退到云端 Web API。
• 批注 PDF 并附加文件。 zotero_annotate 可添加高亮、下划线和笔记，与 Zotero PDF 阅读器创建的对象相同。只需引用段落，Zoteus 就会在 PDF 中找到它，并将批注锚定到段落占据的行上，自动处理换行和连字符，因此无需页面坐标。zotero_attach_file 可将本地文件或 URL 作为附件保存到任意条目下。
• 以 PDF 为依据支持论点。 zotero_get_fulltext 会返回相关段落及其字符偏移量、最近的标题和页面定位信息。如果 Zotero 尚未为 PDF 或 EPUB 建立索引，它会按需提取文本，来源可以是正在运行的桌面应用，也可以是 Zotero 自己的存储文件夹，因此刚添加一分钟的文件也能立即读取。它还可返回 PDF 目录（outline:true）以及按需指定的页面范围，因此处理一本 400 页的书只需几次小型调用，而不必一次性返回整本书。
• 查看页面。 zotero_pdf_images 可将 PDF 的任意页面渲染为模型可见的图像，因此图表、表格、公式或没有文本层的扫描页面都不再难以查看；它还会提取嵌入页面中的图像（类似 pdfimages），并标出每张图在页面上的位置。它使用与读取文本相同的 pdfjs 进行绘制，因此无需安装其他组件。
• 追踪文献。 zotero_scholar 通过 OpenAlex 查询论文的参考文献、引用该论文的作品和相关作品，并在 OpenAlex 不可用时回退到 Crossref；它还可以标出其中哪些已在你的文库中。
• 导入参考文献、查找重复项并合并。 zotero_import 无需 translation-server，即可将 BibTeX、RIS 和 CSL-JSON 作为文本或文件读取，从 PDF 首页中提取 DOI 或 arXiv id，并可在保存前检查文库中是否已有相同条目。zotero_merge_items 会将重复项合并为一条记录：默认先预览，只补充主条目缺少的内容，合并标签、分类和关联，并将笔记和附件重新归入主条目，最后把清空的副本移至废纸篓（参见 docs/importing-bibliographies.md、docs/duplicates-and-merging.md）。
• 开放获取副本和撤稿通知。 如果 OpenAlex 收录了开放获取 PDF，zotero_scholar 会报告该文件；zotero_attach_file 可通过 DOI 获取并附加该文件，同时记录其版本。zotero_scholar 还会报告 Crossref 和 OpenAlex 中的撤稿与更正记录，以记录形式呈现，而非给出结论（docs/open-access-pdfs.md、docs/retraction-notices.md）。
• 证据表和 Word 文档。 zotero-evidence-table 提示词配合 zotero_evidence_table，可将收集的段落整理为 Markdown 或 CSV 表格，其中的引文会与其引用的段落保持一致；zotero_word_document 可生成 .docx 文档，其中的引文是可交互的 Zotero 域代码（docs/evidence-tables.md、docs/word-documents.md；目前尚未验证在 Word 中刷新域的功能）。
• 扫描件、多个文库、本地嵌入。 zotero_get_fulltext 可通过可选的 OCR 引擎读取没有文本层的 PDF（docs/ocr.md）；一个数据目录可为每个文库保存一个搜索索引，zotero_semantic_search 还能一次搜索多个文库（docs/multiple-library-indexes.md）；设置 ZOTEUS_EMBEDDINGS=ollama 可通过本地 Ollama 守护进程生成嵌入，无需 API 密钥（docs/ollama.md）。zoteus index build 可从命令行运行无头索引构建。
• Agent 支持。 提供 34 个具有结构化输出的工具、MCP 资源和提示词，以及适用于 code-execution-with-MCP 模式的自动生成工具树。

工作原理

1. 安装：运行一条 npx 命令，或使用一键安装包 .mcpb。
2. 连接：运行桌面应用，即可免密钥本地访问；也可以粘贴 Zotero API 密钥。
3. 提问。 现在，你的 MCP 客户端可以搜索、引用、添加内容到资料库，并整理资料库。

Zoteus 会检测正在运行的 Zotero 桌面应用并直接与其通信：读取时使用免密钥本地 API（完整 PDF、已保存搜索的结果、语义搜索索引构建），写入时则通过应用本身操作其持有的所有资料库（导入、编辑、标签、分类、合并、附件、注释、废纸篓）。云端 Web API v3 是备用方案；同步、应用未持有的群组资料库，以及应用未运行时的写入，仍需要它。详情请参阅：docs/writing.md。

写入群组资料库。 桌面应用持有的群组（Zotero 10+）可通过应用写入，无需云端密钥；其他群组则通过云端写入，需要 ZOTERO_API_KEY 具有该群组的读写权限。无论哪种情况，群组设置都必须允许你编辑其资料库。请使用 zotero_groups 中的数字 library_id 指定群组（仅设置 library_type:"group" 不够），并从同一群组获取分类键。请参阅群组资料库。

从一段已验证的文献原文开始。 选择客户端和连接方式，检查搜索就绪状态，然后检索并验证一段文献原文。无需建立完整的资料库索引。对于仅本地存储、使用 WebDAV 或扫描版 PDF，请参阅 PDF 可用性。

语义搜索设置。 首次运行 zotero_semantic_search 时，会在后台构建资料库索引。对于超大型资料库，你也可以自行运行 zotero_index (action:"build")，然后轮询 action:"status"，直到构建完成。构建会通过与其他所有读取操作相同的本地优先路径遍历资料库，因此在桌面应用运行时无需云端 API 密钥。这适用于你的个人资料库，以及 Zotero 10+ 中应用持有的任何群组资料库；应用关闭时需要密钥，应用未持有的群组资料库也需要密钥。

通过 API 为大型资料库生成嵌入向量。 对包含 10k 个条目的资料库进行全文构建会产生数万次请求；在默认请求节奏下，无论你的套餐等级如何，速率都会达到 OpenAI 的每分钟令牌数上限。遇到速率限制时，请求会退避并重试，而不是导致构建失败；如果构建仍然提前结束，已建立索引的内容也会保留：再次运行 zotero_index action:"build" 即可继续，它只会为尚无向量的文献原文生成嵌入向量（action:"refresh" 则会从头开始）。如需预先调整请求节奏，请设置 ZOTEUS_EMBED_BATCH_SIZE=256 和 ZOTEUS_EMBED_BATCH_DELAY_MS=8000。请参阅 docs/semantic-search.md。

向量排序需选择启用。 关键词（BM25）搜索在任何环境中开箱即用。本地设备上的向量功能需要 @huggingface/transformers，但桌面扩展包无法包含该依赖（解析后的依赖树，包括 onnxruntime 的原生二进制文件，约为 700 MB）：请将其安装到单独目录中（mkdir -p ~/.zoteus-deps && cd ~/.zoteus-deps && npm init -y && npm i @huggingface/transformers），并将 ZOTEUS_TRANSFORMERS_PATH 设置为 ~/.zoteus-deps/node_modules。不要使用 npm i -g：Claude Desktop 会使用自带的 Node 运行服务，因此通过版本管理器进行全局安装后，依赖会位于扩展从不使用的 Node 旁边。向量不可用时，Zoteus 会在 zotero_index 状态、zotero_whoami 和 zotero_semantic_search 中说明原因，而不会悄无声息地返回空结果。请参阅 docs/semantic-search.md。

配置

变量	默认值	用途
ZOTERO_API_KEY	none	云端身份验证（同步、群组，以及不使用桌面应用时的写入；其他情况下可选）
ZOTEUS_LOCAL	auto	auto|on|off：使用 Zotero 桌面应用（读取 + 个人文库写入）
ZOTEUS_LOCAL_API_KEY	none	预先配置 Zotero 10+ 桌面写入密钥（否则需在应用内授权一次）
ZOTEUS_EMBEDDINGS	local	用于语义搜索的 local|ollama|openai|gemini|off
ZOTEUS_EMBEDDING_MODEL	provider default	该提供方用于生成嵌入的模型，local 也包括在内：德语或其他多语言文库使用 Xenova/multilingual-e5-small，默认使用 Xenova/all-MiniLM-L6-v2
ZOTEUS_EMBEDDING_DTYPE	fp32	设备端模型的权重精度：q8 会将 Xenova/multilingual-e5-small 的下载大小从 465 MB 降至 129 MB。高于 fp32 时，该值会纳入嵌入器标识，因此更改后需要重新构建一次
ZOTEUS_EMBED_BATCH_SIZE	32	每次嵌入调用处理的段落数。如果 API 提供方拒绝整个请求，请调低此值（OpenAI 会对超过 300K tokens 的请求返回 400）
ZOTEUS_EMBED_BATCH_DELAY_MS	0	嵌入调用之间的暂停时间。如果 API 提供方对大型构建触发速率限制，请调高此值：同时设为 256 和 8000，可将全文构建的速度控制在每分钟约 400K tokens
ZOTEUS_INDEX_OWN_WORDS	true	将你自己的子笔记和 PDF 注释编入索引，作为可搜索段落
ZOTEUS_INDEX_FULLTEXT	false	将 PDF 正文编入索引以供语义搜索（选择启用；成本较高）
ZOTEUS_INDEX_BACKEND	auto	搜索索引的存储位置。Node 22.13+ 中，auto 会使用大型文库所需的 SQLite（FTS5）
ZOTEUS_TRANSFORMERS_PATH	none	安装环境无法找到 @huggingface/transformers 时，为 local 嵌入指定其位置（桌面扩展）
ZOTEUS_LOG_FILE	none	将每条日志追加到此文件，适用于无需终端运行的服务
ZOTEUS_ALLOW_DELETE	false	必须设为 true，否则 zotero_delete_items 会拒绝所有调用；除非 ZOTEUS_READ_ONLY=true，否则该工具仍会列出

完整表格见 docs/configuration.md。要运行共享实例或远程实例，请参阅 docs/remote-oauth.md（在回环地址上或通过你自己的代理自托管 OAuth 远程服务）。

文档

zoteus.com/docs · 将 Claude 连接到 Zotero · 将 ChatGPT 连接到 Zotero · 供审阅团队使用的群组文库 · Zoteus 与 zotero-mcp 并排对比

本仓库中的文档：快速入门 · 配置 · 导入与解析器 · 导入参考文献列表 · 重复项与合并 · 架构 · 安全写入 · 威胁模型 · 引文 · Word 文档 · 证据表 · 语义搜索 · 多个文库索引 · Ollama 嵌入 · OCR · 学术背景信息 · 开放获取 PDF · 撤稿通知 · 命令行 · 实验室设置 · 代码执行 · 部署 · 卸载

Zoteus 已作为 io.github.oscardvs/zoteus 列入 MCP 注册表，也收录于 mcpservers.org 和 Citation Styler 的 Zotero MCP 项目概览。

卸载

Zoteus 会将所有派生数据（搜索索引、设备端模型权重、更新检查缓存、获准使用的本地 API 密钥）写入一个目录：如果你设置了 ZOTEUS_DATA_DIR，则写入该目录；否则写入操作系统默认的应用数据路径。停止服务，将其从 MCP 客户端的配置中移除，然后删除该目录即可；你的 Zotero 文库位于其他位置，此操作不会影响它。完整步骤和各平台路径：docs/uninstall.md。

隐私

Zoteus 在你的计算机或你配置的服务上运行。默认关闭使用情况日志记录。工具结果会发送到你选择的 AI 客户端；启用的功能会连接其所需的 Zotero 及学术、PDF 或嵌入服务。完整政策： PRIVACY.md。

贡献

欢迎贡献；请参阅 CONTRIBUTING.md。Zoteus 采用 MIT 许可证。

致谢

本项目基于 Model Context Protocol、Zotero Web API、citeproc-js 和 Citation Style Language 构建。与 Corporation for Digital Scholarship / Zotero 没有关联，也未获得其认可。

citeproc-js 实现了 Citation Style Language。（c）Frank Bennett，依据 Common Public Attribution License 1.0 使用。https://citationstyles.org/ 第三方依赖声明汇总于 THIRD_PARTY_NOTICES.md。