Zotero MCP Server：无需打开 Zotero，10,000 篇 PDF 检索仅约 20 ms

Q: 我需要一直让 Zotero 开着，MCP 服务器才能工作吗？

不需要 —— 就检索和阅读而言。核心直接读取你的 Zotero 数据目录（zotero.sqlite 和 storage/），因此即使 Zotero 已关闭，甚至在那台机器上根本没运行 Zotero 桌面应用时，建索引和检索也能工作。只有三个写工具（导入条目、添加笔记、批量修改标签/分类集合）需要经过 Zotero 的本地 API，所以那些操作需要 Zotero 处于打开状态。

Q: Zotero MCP 服务器除了 JavaScript 也支持 Python 吗？

支持。有两个功能对等的 Shell：面向 JavaScript/Node 用户的 npm 包 @docsagent/mcp-zotero，以及面向 Python 3.10+ 的 PyPI 包 docsagent-mcp-zotero。两者都暴露同样 8 个工具，schema、错误码和写入闸门一致，并且都管理同一个内置的 C++ 核心。

Q: AI 智能体能修改我的 Zotero 文献库吗？

只有你允许时才行。除非把 enableWrites 设为 true，否则写工具不会被注册；未确认的调用只返回预览；已确认的写入受速率限制（默认 30/hour）；超过 20 个条目的批量操作需要显式确认。

如果你用过第一代 Zotero MCP server，一定记得那套固定流程：Zotero 必须开着，本地 API 必须启用，而每次查询都要在你的文献库里一条元数据一条元数据地慢慢爬。做演示还行；但当你的库里存着 5,000 篇 PDF，而智能体在你一句话还没打完之前就发起二十次检索时，就完全不行了。

全新的 Zotero MCP Server —— @docsagent/mcp-zotero v4.0.1，于 2026 年 9 月 21 日发布 —— 是一台完全不同的机器。它在常驻的原生 C++ 检索引擎之上提供两种 Shell（JavaScript 与 Python），直接读取你的 Zotero 数据目录。检索无需打开 Zotero，而拥有 10,000+ 篇 PDF 的文献库对 Claude Code、Cursor、Codex、Claude Desktop、Gemini CLI、Qwen Code、Cline 或任何其他 MCP 客户端来说，都会变成一个毫秒级的知识库。

这是一篇新版本指南：改了什么、如何在两种运行时中安装、你的智能体可用的 8 个工具，以及真正大型文献库的基准数据。

Zotero MCP Server 4.0 的新变化

两种 Shell，一个核心。 同一套工具契约既以 TypeScript 包的形式发布在 npm（@docsagent/mcp-zotero），也以 Python 包的形式发布在 PyPI（docsagent-mcp-zotero）。选你技术栈已经在用的运行时即可 —— 工具、schema、错误码和写入闸门完全一致。
无需启动 Zotero。 C++ 核心直接读取 ~/Zotero/zotero.sqlite 以及 storage/ 目录，因此即使 Zotero 已关闭 —— 甚至那台机器上根本没装 —— 建索引和检索也照常工作。
常驻服务，而非每次调用都起子进程。 核心在后台运行于 http://127.0.0.1:23120/rpc，随文献库变化重建索引，并在 MCP 客户端多次重启之间保持热态。你的智能体永远不用付冷启动的税。
为大型文献库而生。 倒排索引的 BM25 全文检索 + 段落排序，在 1,000+ 篇 PDF 上约 15 ms 完成，内存占用只有几百 MB 而非数 GB。
8 个 MCP 工具（5 个读 + 3 个写），带 JSON schema 校验的参数、token 预算、结果去重，以及三层写入安全闸门。
两种传输方式。 本地 MCP 客户端用 stdio；远程部署时用 Streamable HTTP（/mcp），带来源校验、API key 或 OAuth 2.0（RFC 7662）认证以及逐请求 RBAC。
一个配置文件。 ~/.docsagent/config.json 由 JS Shell、Python Shell 和 C++ 核心共用。

工作原理：一个原生核心上的两种 Shell

MCP Client (Claude Code / Claude Desktop / Cursor / Codex / Gemini CLI / Qwen Code / Cline)
        │  stdio (local)   or   Streamable HTTP  /mcp  (remote)
        ▼
MCP shell  ← @docsagent/mcp-zotero  (TypeScript)  or  docsagent-mcp-zotero  (Python)
   · spec-driven tool schemas, argument validation, token budget, dedup
   · write orchestration via the Zotero local API, write safety gate, RBAC
        │  JSON-RPC 2.0 over HTTP  ({coreHost}:{httpPort}/rpc)
        ▼
DocsAgent Core  (resident C++ engine)
   · reads ~/Zotero/zotero.sqlite + storage/ directly
   · builds & serves the full-text index (BM25 + passage ranking)

这种拆分很关键。Shell 很薄 —— 它持有工具 schema、校验参数、执行 token 预算，从不触碰你的 Zotero 文件。重活由核心用 C++ 完成，这正是同一个引擎能为 npm 包和 PyPI 包提供逐字节一致行为的原因。

快速开始：3 步把 Zotero 接入你的 AI 智能体

方案 A —— JavaScript / npm

# 1. start the resident search core (background service)
npx @docsagent/mcp-zotero start
npx @docsagent/mcp-zotero status    # pid / endpoint / version

然后把这个服务器加进你的 MCP 客户端设置（Claude Desktop、Cursor、Cline、Qwen Code……）：

{
  "mcpServers": {
    "docsagent-zotero": {
      "command": "npx",
      "args": ["-y", "@docsagent/mcp-zotero"]
    }
  }
}

方案 B —— Python

# 1. install the Python shell (ships the same bundled core binaries)
pip install docsagent-mcp-zotero
docsagent-mcp-zotero core start
docsagent-mcp-zotero core status

然后用同样的方式注册 Python Shell：

{
  "mcpServers": {
    "docsagent-zotero": {
      "command": "docsagent-mcp-zotero",
      "args": []
    }
  }
}

重启你的 MCP 客户端，问它类似*“我的 Zotero 库里关于钠离子电池容量衰减都说了些什么？”*这样的问题 —— 智能体会调用 search，拿到带 zotero:KEY 引用的 BM25 排序段落，并基于你的 PDF 而不是开放网络来回答。

两个 CLI 也都提供核心生命周期命令 —— start、stop、restart、status（Python 把它们放在 core 子命令下，即 docsagent-mcp-zotero core restart）—— 另外还有 --transport streamable-http，用于通过网络对外提供 /mcp。

你的智能体可以调用的 8 个工具

工具	类型	作用
`list_sources`	读	列出每个可检索来源及其能力和文档数量。请先调用它。
`search`	读	跨库检索条目、标注或笔记；`ids` / `snippets` / `full` 三种深度，支持按标签、年份范围、条目类型、作者、分类集合过滤。
`get_content`	读	以查询排序的段落（`k`）或带偏移分页的全文读取单条记录。
`get_metadata`	读	元数据、摘要、标注、笔记与引用（BibTeX / CSL-JSON / 格式化）。
`list_library`	读	浏览分类集合、条目、标签、保存的检索和独立笔记。
`import_item`	写	导入本地 PDF，或解析 DOI / ISBN / arXiv ID，可选自动归类到分类集合。
`add_note`	写	把 Markdown 笔记作为 Zotero 子笔记写回某个条目，支持回滚。
`batch_modify`	写	对最多 200 个条目批量添加/移除分类集合或标签。

除非你设置 enableWrites: true，否则写工具根本不会被注册。即便如此，未确认的调用只会返回预览且不消耗配额，已确认的写入受速率限制（默认 30/hour），任何超过 20 个条目的 batch_modify 都会返回 requiresConfirmation。智能体可以整天读你的文献库，但无法悄悄改写它。

性能：10,000 篇 PDF、42 GB，约 7 分钟建好索引

这个 MCP 服务器中的核心，与 PapersGPT 的检索基准测试背后的索引与检索引擎是同一个。以下数据来自一次真实的 Zotero 安装：

文献库规模	原始数据	索引构建	平均查询耗时	内存（RSS）	索引大小
1,000 篇 PDF	4.2 GB	51.5 s	13.1 ms	353 MB	100 MB
10,000 篇 PDF	42 GB	421 s（7 m 01 s）	19.5 ms	2.21 GB	901 MB

在一台刻意压低配置的机器上 —— 4 cores / 8 GB RAM —— 为 1,506 篇 PDF（4.5 GB）建索引耗时 141 秒，进程占用 227 MB 内存，平均检索耗时 ~15 ms。真正重要的规律是：

索引构建大致线性扩展。 PDF 数量翻十倍，构建时间也翻十倍 —— 而且这是每新增一篇文档才付一次的成本，不是每个问题都要付。
检索耗时保持平稳。 1,000 篇论文时 13 ms，10,000 篇时 19.5 ms。多存论文不会让你的智能体变慢。
内存保持克制。 自动卸载机制让 42 GB 的文献库能在约 2 GB 内存内保持可检索。
一切都离线。 建索引和检索都不调用云端，所以在飞机上、在封闭的实验室网络里、或在禁运审查期间都能用。

为什么“无需启动 Zotero”改变了工作流

传统的 Zotero MCP 服务器是包在 Zotero 本地 API（http://localhost:23119/api）外面的薄壳：没有 Zotero 进程，就没有答案。这一项依赖决定了一切 —— 你无法在容器、远程开发机、无头脚本或 SSH 会话中检索自己的文献库；无法在 Zotero 正在同步时检索；而且每次调用都是一次请求往返，而不是一次索引查找。

因为 DocsAgent 核心直接读取数据库，工作流中“读”的那一半就与 Zotero 应用解耦了：

	基于 API 的 Zotero MCP 服务器	Zotero MCP Server 4.0
检索时 Zotero 必须运行	是	否
检索后端	Zotero 本地 API 调用	原生 C++ BM25 + 段落索引
10,000 篇 PDF 的查询延迟	数百毫秒到数秒	~20 ms
运行时	通常只有一种	JavaScript + Python
远程 / HTTP 传输	罕见	带认证与 RBAC 的 Streamable HTTP
写入安全	通常靠手动	三层闸门 + 速率限制

一个诚实的提醒：写入仍然要经过 Zotero 自己的本地 API，这样 Zotero 才能始终是你文献库的唯一事实来源。如果你希望智能体导入 PDF、添加笔记或重新打标签，这一步就需要 Zotero 处于运行状态。建索引、检索和阅读则永远不需要。

使用场景：研究者实际会用它做什么

在编辑器里用 Claude Code 或 Cursor 做研究。 一边写论文，一边让智能体直接从你自己的文献库里取出段落、摘要和 BibTeX —— 不用复制粘贴，不用开一堆浏览器标签。
在终端里用 Codex 或 Gemini CLI 做文献初筛。 “找出我库里每一篇能量转换效率超过 20% 的论文，并把它们加到 Perovskite 分类集合里” —— search 之后接 batch_modify。
离线阅读。 在飞机上或野外，索引在本地回答问题，什么都不需要联网。
群组文献库。 把 zoteroGroups 指向你们实验室的共享文献库，和个人文献库一起检索。
智能体技能。 该项目还发布了一份可移植的 SKILL.md，因此支持技能（skills）的智能体可以被教会“先检索再引用”的工作流，而不必去猜工具参数。

隐私与安全

你的 PDF 永远不会离开你的机器：建索引和检索 100% 本地完成，任何文档都不会发送到任何云服务。当你主动启用写入时，写入是受闸门约束、可预览、受速率限制且可回滚的。当你主动把服务器暴露在 HTTP 上时，你得到的是来源校验、token 认证和逐请求 RBAC，而不是一个敞开的端口。

常见问题

我需要一直让 Zotero 开着，MCP 服务器才能工作吗？

不需要 —— 就检索和阅读而言。核心直接读取你的 Zotero 数据目录（zotero.sqlite 和 storage/），因此即使 Zotero 已关闭，甚至在那台机器上根本没运行 Zotero 桌面应用时，建索引和检索也能工作。只有三个写工具（导入条目、添加笔记、批量修改标签/分类集合）需要经过 Zotero 的本地 API，所以那些操作需要 Zotero 处于打开状态。

Zotero MCP 服务器除了 JavaScript 也支持 Python 吗？

支持。有两个功能对等的 Shell：面向 JavaScript/Node 用户的 npm 包 @docsagent/mcp-zotero，以及面向 Python 3.10+ 的 PyPI 包 docsagent-mcp-zotero。两者都暴露同样 8 个工具，schema、错误码和写入闸门一致，并且都管理同一个内置的 C++ 核心。

它能处理多大的 Zotero 文献库？

数千篇 PDF 的文献库是常态：1,000 篇 PDF（4.2 GB）约 52 秒建好索引，查询约 13 ms；10,000 篇 PDF（42 GB）约 7 分钟建好索引，查询约 19.5 ms。索引构建时间大致随文献库规模线性增长，而查询延迟基本保持恒定。

我的 Zotero 文献库会被上传到某处吗？

不会。核心完全在你的机器上构建并提供索引服务，检索也不需要任何网络访问。关于你论文的任何信息都不会发送给 PapersGPT 或任何第三方。

AI 智能体能修改我的 Zotero 文献库吗？

只有你允许时才行。除非把 enableWrites 设为 true，否则写工具不会被注册；未确认的调用只返回预览；已确认的写入受速率限制（默认 30/hour）；超过 20 个条目的批量操作需要显式确认。

支持哪些 AI 客户端？

任何 MCP 客户端。项目文档覆盖了 Claude Desktop、Claude Code、Cursor、Codex、Cline、Gemini CLI 和 Qwen Code，并提供了 Streamable HTTP 传输，供那些通过远程连接而非 stdio 接入的客户端使用。

这和更早的 PapersGPT MCP 方案有什么区别？

更早的方案是围绕 Zotero 本地 API 构建的单用途桥梁。4.0 版用一个常驻的 C++ 检索引擎取代了它，新增了一等公民的 Python Shell，让检索不再依赖 Zotero 运行，并把现实可用上限从“几百篇论文”提升到 10,000+ 篇 PDF。旧版文章仍作为历史参考保留在线。

开始使用

npx @docsagent/mcp-zotero start

这一条命令就能把你的 Zotero 文献库变成私有、毫秒级响应的知识库，供你已经在用的任何 AI 智能体使用。安装说明、工具 schema 和完整配置参考都在 docsagent 仓库里，更多背景可以看 MCP 服务器页面。

想要在 Zotero 内部使用同一个引擎 —— 应用内对话、AutoPilot 批量阅读、本地 LLM？请见 Zotero AI 插件对比和 PapersGPT。习惯在终端工作的用户还应该读一读 Zotero CLI 指南。